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

# Trace AI Agent Activity with Trident SDK

> Automatically capture every prompt, tool call, and LLM response your agent makes using the Trident SDK — with zero-config PII redaction.

Tracing gives you a complete audit trail of everything your agent does: every prompt it receives, every LLM call it makes, every tool it invokes, and every response it generates. Without a trace, a misbehaving agent is a black box — you know something went wrong, but not where, why, or what the model actually said. Trident's tracing layer captures the full picture in production so you can investigate incidents, verify firewall decisions, and feed accurate data into red-team replay.

## How tracing works

The Trident SDK wraps [OpenLLMetry](https://github.com/traceloop/openllmetry) (the open-source OpenTelemetry instrumentation layer for LLMs, built by Traceloop). When you call `trident.init()`, the SDK patches every LLM client loaded in the same process — OpenAI, Anthropic, LangChain, and others — so each LLM call automatically becomes an OTEL span. Those spans are shipped to your Trident project's OTLP ingest endpoint (`/api/public/otel/v1/traces`) using Basic auth derived from your project key pair.

You do not need to wrap individual calls or modify your agent logic. One `init()` call at startup covers everything in the process.

## Installation and setup

<Tabs>
  <Tab title="TypeScript">
    Install the SDK from npm:

    ```bash theme={null}
    npm install @vouch-ai/sdk
    ```

    Call `trident.init()` once at application startup, before any LLM calls:

    ```typescript theme={null}
    import { trident } from "@vouch-ai/sdk";

    trident.init({
      projectPk: process.env.TRIDENT_PROJECT_PUBLIC_KEY,
      projectSk: process.env.TRIDENT_PROJECT_SECRET_KEY,
      agentId: "prod-rag-bot", // optional — scopes spans to this agent
    });

    // Any LLM call after init() is automatically traced.
    import OpenAI from "openai";
    const openai = new OpenAI();
    await openai.chat.completions.create({ model: "gpt-4o", messages: [...] });
    ```
  </Tab>

  <Tab title="Python">
    Install the SDK from PyPI:

    ```bash theme={null}
    pip install vouch-sdk
    ```

    Call `vouch_sdk.init()` once at application startup:

    ```python theme={null}
    import vouch_sdk

    vouch_sdk.init(
        project_pk="pk-...",
        project_sk="sk-...",
        agent_id="prod-rag-bot",  # optional — scopes spans to this agent
    )

    # Any LLM call after init() is automatically traced.
    from openai import OpenAI
    client = OpenAI()
    client.chat.completions.create(model="gpt-4o", messages=[...])
    ```
  </Tab>
</Tabs>

## Environment variables

Instead of passing keys directly to `init()`, you can set environment variables and call `init()` with no arguments:

```bash theme={null}
TRIDENT_PROJECT_PUBLIC_KEY=pk-...
TRIDENT_PROJECT_SECRET_KEY=sk-...
TRIDENT_AGENT_ID=prod-rag-bot       # optional
```

The TypeScript and Python SDKs also read `VOUCH_PROJECT_PUBLIC_KEY` and `VOUCH_PROJECT_SECRET_KEY` as back-compat aliases.

## Zero-code option for Node.js

If you want to add tracing to an existing Node.js application without modifying its source code, use the `--require` flag to load the SDK's auto-instrumentation register at process start:

```bash theme={null}
node --require @vouch-ai/sdk/register server.js
```

Set your `TRIDENT_PROJECT_PUBLIC_KEY` and `TRIDENT_PROJECT_SECRET_KEY` environment variables before running the command. No code changes required.

## What each trace contains

Every traced LLM call produces a span with the following attributes:

| Attribute           | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| **Prompt text**     | The full messages array sent to the model                   |
| **Model name**      | The model identifier (e.g. `gpt-4o`, `claude-3-5-sonnet`)   |
| **Tool calls**      | Any function/tool calls the model made, including arguments |
| **MCP invocations** | Model Context Protocol tool calls and their results         |
| **Response**        | The full model response text                                |
| **Latency**         | End-to-end call duration in milliseconds                    |
| **Token counts**    | Prompt tokens, completion tokens, and total                 |

Spans are grouped into traces by request, so a single multi-step agent run — retrieval, reasoning, tool call, summarization — appears as one coherent trace tree in the dashboard.

## PII redaction

The SDK scrubs sensitive data from span attributes **inside your process**, before any trace data is transmitted to Trident. The following patterns are redacted and replaced with a labelled placeholder (e.g. `[EMAIL]`, `[CREDIT_CARD]`):

* **Email addresses** — `user@example.com`
* **Credit card numbers** — validated with Luhn checksum to avoid false positives
* **US Social Security Numbers** — `123-45-6789`
* **AWS access key IDs** — `AKIA...`, `ASIA...`, `AIDA...`
* **JSON Web Tokens** — three-part `eyJ...` strings
* **API keys** — `sk-` and `sk-ant-` prefixed secrets
* **IBANs** — international bank account numbers
* **IPv4 addresses**
* **Phone numbers**

Redaction is enabled by default. To supply your own rules, pass a `redactPII` option to `init()`:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { trident } from "@vouch-ai/sdk";
    import type { PiiRule } from "@vouch-ai/sdk";

    const myRules: PiiRule[] = [
      { name: "EMPLOYEE_ID", pattern: /EMP-\d{6}/g },
    ];

    trident.init({
      projectPk: process.env.TRIDENT_PROJECT_PUBLIC_KEY,
      projectSk: process.env.TRIDENT_PROJECT_SECRET_KEY,
      redactPII: { rules: myRules }, // replaces the built-in rule set
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import vouch_sdk
    from vouch_sdk import PiiRule
    import re

    my_rules = [
        PiiRule("EMPLOYEE_ID", re.compile(r"EMP-\d{6}")),
    ]

    vouch_sdk.init(
        project_pk="pk-...",
        project_sk="sk-...",
        redact_pii={"rules": my_rules},  # replaces the built-in rule set
    )
    ```
  </Tab>
</Tabs>

To disable PII redaction entirely, pass `redactPII: false` (TypeScript) or `redact_pii=False` (Python). **Only do this if you have verified that your traces contain no sensitive data.**

## Viewing traces

Open the **Traces** tab in the [Trident dashboard](https://app.tryvouch.ai) to see all captured spans. You can filter by:

* **Agent** — scope the view to a specific `agentId`
* **Time range** — narrow to a deployment window or incident window
* **Model** — compare behaviour across model versions
* **Trace ID** — jump directly to the span linked from a finding

Select any trace to see the full span tree, including prompt text (post-redaction), model responses, tool call arguments, and latency breakdown.

<Note>
  Tracing overhead is sub-millisecond. The SDK uses OpenTelemetry's `BatchSpanProcessor` by default, which buffers spans and exports them asynchronously. Your agent's request latency is not measurably affected.
</Note>