> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness

> Trace DeepSeek Harness agent sessions in Braintrust to observe user turns, LLM steps, tool calls, and child session interactions

[DeepSeek Harness](https://deepseek.com/harness/) is a TypeScript agent harness from DeepSeek AI built on the Cordis plugin system. Braintrust traces DeepSeek Harness sessions, turns, LLM steps, tool calls, and nested child sessions.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

  Set your Braintrust API key as an environment variable. The plugin reads it automatically when no key is configured explicitly in the Cordis patch.

  ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  BRAINTRUST_API_KEY=<your-braintrust-api-key>
  ```

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  To trace DeepSeek Harness sessions, add the Braintrust plugin to your Harness profile using the `dsh` CLI.

  <Steps>
    <Step title="Add the Braintrust plugin">
      Run the following command, replacing `web` with the Harness profile you want to instrument:

      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      dsh plugin --profile web add @braintrust/deepseek-harness
      ```

      The command installs `@braintrust/deepseek-harness` and applies its bundled Cordis patch to the selected profile. Traces appear in the project named `DeepSeek Harness` in your Braintrust organization.
    </Step>

    <Step title="Configure the plugin (optional)">
      To override the defaults, add a `braintrust` entry to the profile's `cordis.patch.yml`:

      ```yaml title="cordis.patch.yml" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      - id: braintrust
        config:
          apiKey: <your-api-key>
          projectName: DeepSeek Harness
          metadata:
            environment: production
      ```

      The configurable fields are:

      * `apiKey` - Braintrust API key. Falls back to `BRAINTRUST_API_KEY` when omitted. Set it under **Settings > Plugins** in Harness. It is declared as a secret field so the settings UI handles it as a credential.
      * `projectName` - Braintrust project receiving Harness traces. Defaults to `DeepSeek Harness`.
      * `metadata` - Key-value pairs added to every top-level turn trace.
      * `orgName` - Braintrust organization name.
      * `appUrl` - Braintrust deployment URL for self-hosted deployments.
    </Step>
  </Steps>

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  Braintrust captures:

  * Turn spans (`deepseek_harness.turn`), as individual traces, with user messages as input, the final assistant text as output, aggregated token metrics, and `deepseek_harness.session_id`, `deepseek_harness.turn`, and `deepseek_harness.stop_reason` in metadata.
  * LLM step spans (`deepseek_harness.step`), as LLM spans nested under their turn, with the full conversation history (including the system prompt) as input, the model response as an OpenAI-compatible choices array as output, and model, provider, and request parameters in metadata.
  * Tool call spans (named after the tool), as tool spans nested under their turn, with tool arguments as input and the tool result as output.
  * Child session spans nested under the tool span that triggered them, preserving the full call hierarchy across spawned sub-sessions.
  * Token usage metrics (prompt, completion, and total tokens, plus cache read, cache creation, and reasoning tokens when the model provides them) on LLM step spans, with aggregated totals rolled up to the parent turn span.
  * Time-to-first-token on LLM step spans.
  * Image attachments from the Harness attachment store, normalized and attached inline.
  * Errors captured on every span.

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [`@braintrust/deepseek-harness` on npm](https://www.npmjs.com/package/@braintrust/deepseek-harness)
  * [Braintrust tracing guide](/docs/instrument/trace-llm-calls)
</View>