# Instrument AI Agents | Sentry for Solid

With [Sentry AI Agent Monitoring](https://docs.sentry.io/product/insights/ai/agents/dashboard.md), you can monitor and debug your AI systems with full-stack context. You'll be able to track key insights like token usage, latency, tool usage, and error rates. AI Agent Monitoring data will be fully connected to your other Sentry data like logs, errors, and traces.

As a prerequisite to setting up AI Agent Monitoring in browser applications, you'll need to first [set up tracing](https://docs.sentry.io/platforms/javascript/guides/solid/tracing.md).

**Browser applications require manual instrumentation.** Unlike Node.js applications, the JavaScript SDK does not provide automatic instrumentation for AI libraries in the browser. You must use manual instrumentation techniques to capture AI agent spans.

## [Manual Instrumentation Options](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#manual-instrumentation-options)

There are two ways to instrument AI agents in browser applications:

1. **Using Integration Helpers** - For supported AI libraries (recommended)
2. **Custom Span Creation** - For unsupported libraries or custom AI implementations

## [Using Integration Helpers](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#using-integration-helpers)

For some AI libraries, Sentry provides manual instrumentation helpers that simplify span creation. These helpers handle the complexity of creating properly structured spans with the correct attributes for AI Agent Monitoring.

### [Supported AI Libraries](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#supported-ai-libraries)

The following AI libraries have helper functions available for browser applications:

* **[OpenAI](https://docs.sentry.io/platforms/javascript/guides/solid/configuration/integrations/openai.md)**
* **[Anthropic](https://docs.sentry.io/platforms/javascript/guides/solid/configuration/integrations/anthropic.md)**
* **[Google Gen AI SDK](https://docs.sentry.io/platforms/javascript/guides/solid/configuration/integrations/google-genai.md)**
* **[LangChain](https://docs.sentry.io/platforms/javascript/guides/solid/configuration/integrations/langchain.md)**
* **[LangGraph](https://docs.sentry.io/platforms/javascript/guides/solid/configuration/integrations/langgraph.md)**

Each integration page includes browser-specific examples showing how to use the helper functions with options like `recordInputs` and `recordOutputs` to control what data is captured.

## [Manual Span Creation](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#manual-span-creation)

If you're using an AI library that Sentry doesn't provide helpers for, or if you have a custom AI implementation, you can manually create spans to capture AI agent operations. For your AI agents data to show up in the Sentry [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/agents/), spans must have well-defined names and data attributes following OpenTelemetry Semantic Conventions for Generative AI.

## [Spans](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#spans)

### [Invoke Agent Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#invoke-agent-span)

Invoke Agent span attributes

Describes AI agent invocation.

* The spans `op` MUST be `"gen_ai.invoke_agent"`.
* The span `name` SHOULD be `"invoke_agent {gen_ai.agent.name}"`.
* The `gen_ai.operation.name` attribute MUST be `"invoke_agent"`.
* The `gen_ai.agent.name` attribute SHOULD be set to the agent's name. (e.g. `"Weather Agent"`)
* All [Common Span Attributes](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).

Additional attributes on the span:

| Data Attribute                         | Type   | Requirement Level | Description                                                                          | Example                                                                                                           |
| -------------------------------------- | ------ | ----------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `gen_ai.request.available_tools`       | string | optional          | List of objects describing the available tools. **\[0]**                             | `"[{\"name\": \"random_number\", \"description\": \"...\"}, {\"name\": \"query_db\", \"description\": \"...\"}]"` |
| `gen_ai.request.frequency_penalty`     | float  | optional          | Model configuration parameter.                                                       | `0.5`                                                                                                             |
| `gen_ai.request.max_tokens`            | int    | optional          | Model configuration parameter.                                                       | `500`                                                                                                             |
| `gen_ai.request.messages`              | string | optional          | List of objects describing the messages (prompts) sent to the LLM **\[0]**, **\[1]** | `"[{\"role\": \"system\", \"content\": [{...}]}, {\"role\": \"system\", \"content\": [{...}]}]"`                  |
| `gen_ai.request.presence_penalty`      | float  | optional          | Model configuration parameter.                                                       | `0.5`                                                                                                             |
| `gen_ai.request.temperature`           | float  | optional          | Model configuration parameter.                                                       | `0.1`                                                                                                             |
| `gen_ai.request.top_p`                 | float  | optional          | Model configuration parameter.                                                       | `0.7`                                                                                                             |
| `gen_ai.response.tool_calls`           | string | optional          | The tool calls in the model’s response. **\[0]**                                     | `"[{\"name\": \"random_number\", \"type\": \"function_call\", \"arguments\": \"...\"}]"`                          |
| `gen_ai.response.text`                 | string | optional          | The text representation of the model’s responses. **\[0]**                           | `"[\"The weather in Paris is rainy\", \"The weather in London is sunny\"]"`                                       |
| `gen_ai.usage.input_tokens.cached`     | int    | optional          | The number of cached tokens used in the AI input (prompt)                            | `50`                                                                                                              |
| `gen_ai.usage.input_tokens`            | int    | optional          | The number of tokens used in the AI input (prompt).                                  | `10`                                                                                                              |
| `gen_ai.usage.output_tokens.reasoning` | int    | optional          | The number of tokens used for reasoning.                                             | `30`                                                                                                              |
| `gen_ai.usage.output_tokens`           | int    | optional          | The number of tokens used in the AI response.                                        | `100`                                                                                                             |
| `gen_ai.usage.total_tokens`            | int    | optional          | The total number of tokens used to process the prompt. (input and output)            | `190`                                                                                                             |

* **\[0]:** Span attributes only allow primitive data types (like `int`, `float`, `boolean`, `string`). This means you need to use a stringified version of a list of dictionaries. Do NOT set `[{"foo": "bar"}]` but rather the string `"[{\"foo\": \"bar\"}]"`.
* **\[1]:** Each message item uses the format `{role:"", content:""}`. The `role` can be `"user"`, `"assistant"`, or `"system"`. The `content` can be either a string or a list of dictionaries.

#### [Example of an Invoke Agent Span:](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#example-of-an-invoke-agent-span)

```javascript
// Example agent implementation for demonstration
const myAgent = {
  name: "Weather Agent",
  modelProvider: "openai",
  model: "gpt-4o-mini",
  async run() {
    // Agent implementation
    return {
      output: "The weather in Paris is sunny",
      usage: {
        inputTokens: 15,
        outputTokens: 8,
      },
    };
  },
};

Sentry.startSpan(
  {
    op: "gen_ai.invoke_agent",
    name: `invoke_agent ${myAgent.name}`,
    attributes: {
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.request.model": myAgent.model,
      "gen_ai.agent.name": myAgent.name,
    },
  },
  async (span) => {
    // run the agent
    const result = await myAgent.run();

    // set agent response
    // we assume result.output is a string
    // type of `gen_ai.response.text` needs to be a string
    span.setAttribute(
      "gen_ai.response.text",
      JSON.stringify([result.output]),
    );

    // set token usage
    // we assume the result includes the tokens used
    span.setAttribute(
      "gen_ai.usage.input_tokens",
      result.usage.inputTokens,
    );
    span.setAttribute(
      "gen_ai.usage.output_tokens",
      result.usage.outputTokens,
    );

    return result;
  },
);
```

### [AI Client Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#ai-client-span)

AI Client span attributes

* The span `op` MUST be `"gen_ai.{gen_ai.operation.name}"`. (e.g. `"gen_ai.request"`)
* The span `name` SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}"`. (e.g. `"chat o3-mini"`)
* All [Common Span Attributes](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).

Additional attributes on the span:

| Data Attribute                         | Type   | Requirement Level | Description                                                                          | Example                                                                                                           |
| -------------------------------------- | ------ | ----------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `gen_ai.request.available_tools`       | string | optional          | List of objects describing the available tools. **\[0]**                             | `"[{\"name\": \"random_number\", \"description\": \"...\"}, {\"name\": \"query_db\", \"description\": \"...\"}]"` |
| `gen_ai.request.frequency_penalty`     | float  | optional          | Model configuration parameter.                                                       | `0.5`                                                                                                             |
| `gen_ai.request.max_tokens`            | int    | optional          | Model configuration parameter.                                                       | `500`                                                                                                             |
| `gen_ai.request.messages`              | string | optional          | List of objects describing the messages (prompts) sent to the LLM **\[0]**, **\[1]** | `"[{\"role\": \"system\", \"content\": [{...}]}, {\"role\": \"system\", \"content\": [{...}]}]"`                  |
| `gen_ai.request.presence_penalty`      | float  | optional          | Model configuration parameter.                                                       | `0.5`                                                                                                             |
| `gen_ai.request.temperature`           | float  | optional          | Model configuration parameter.                                                       | `0.1`                                                                                                             |
| `gen_ai.request.top_p`                 | float  | optional          | Model configuration parameter.                                                       | `0.7`                                                                                                             |
| `gen_ai.response.tool_calls`           | string | optional          | The tool calls in the model's response. **\[0]**                                     | `"[{\"name\": \"random_number\", \"type\": \"function_call\", \"arguments\": \"...\"}]"`                          |
| `gen_ai.response.text`                 | string | optional          | The text representation of the model's responses. **\[0]**                           | `"[\"The weather in Paris is rainy\", \"The weather in London is sunny\"]"`                                       |
| `gen_ai.usage.input_tokens.cached`     | int    | optional          | The number of cached tokens used in the AI input (prompt)                            | `50`                                                                                                              |
| `gen_ai.usage.input_tokens`            | int    | optional          | The number of tokens used in the AI input (prompt).                                  | `10`                                                                                                              |
| `gen_ai.usage.output_tokens.reasoning` | int    | optional          | The number of tokens used for reasoning.                                             | `30`                                                                                                              |
| `gen_ai.usage.output_tokens`           | int    | optional          | The number of tokens used in the AI response.                                        | `100`                                                                                                             |
| `gen_ai.usage.total_tokens`            | int    | optional          | The total number of tokens used to process the prompt. (input and output)            | `190`                                                                                                             |

* **\[0]:** Span attributes only allow primitive data types. This means you need to use a stringified version of a list of dictionaries. Do NOT set `[{"foo": "bar"}]` but rather the string `"[{\"foo\": \"bar\"}]"`.
* **\[1]:** Each message item uses the format `{role:"", content:""}`. The `role` can be `"user"`, `"assistant"`, or `"system"`. The `content` can be either a string or a list of dictionaries.

#### [Example AI Client Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#example-ai-client-span)

```javascript
// Example implementation for demonstration
const myAi = {
  modelProvider: "openai",
  model: "gpt-4o-mini",
  modelConfig: {
    temperature: 0.1,
    presencePenalty: 0.5,
  },
  async createMessage(messages, maxTokens) {
    // AI implementation
    return {
      output:
        "Here's a joke: Why don't scientists trust atoms? Because they make up everything!",
      usage: {
        inputTokens: 12,
        outputTokens: 24,
      },
    };
  },
};

Sentry.startSpan(
  {
    op: "gen_ai.chat",
    name: `chat ${myAi.model}`,
    attributes: {
      "gen_ai.operation.name": "chat",
      "gen_ai.request.model": myAi.model,
    },
  },
  async (span) => {
    // set up messages for LLM
    const maxTokens = 1024;
    const prompt = "Tell me a joke";
    const messages = [{ role: "user", content: prompt }];

    // set chat request data
    span.setAttribute("gen_ai.request.messages", JSON.stringify(messages));
    span.setAttribute("gen_ai.request.max_tokens", maxTokens);
    span.setAttribute(
      "gen_ai.request.temperature",
      myAi.modelConfig.temperature,
    );
    span.setAttribute(
      "gen_ai.request.presence_penalty",
      myAi.modelConfig.presencePenalty,
    );

    // ask the LLM
    const result = await myAi.createMessage(messages, maxTokens);

    // set response
    // we assume result.output is a string
    // type of `gen_ai.response.text` needs to be a string
    span.setAttribute(
      "gen_ai.response.text",
      JSON.stringify([result.output]),
    );

    // set token usage
    // we assume the result includes the tokens used
    span.setAttribute(
      "gen_ai.usage.input_tokens",
      result.usage.inputTokens,
    );
    span.setAttribute(
      "gen_ai.usage.output_tokens",
      result.usage.outputTokens,
    );

    return result;
  },
);
```

### [Execute Tool Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#execute-tool-span)

Execute Tool span attributes

Describes a tool execution.

* The span `op` MUST be `"gen_ai.execute_tool"`.
* The span `name` SHOULD be `"execute_tool {gen_ai.tool.name}"`. (e.g. `"execute_tool query_database"`)
* The `gen_ai.tool.name` attribute SHOULD be set to the name of the tool. (e.g. `"query_database"`)
* All [Common Span Attributes](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).

Additional attributes on the span:

| Data Attribute            | Type   | Requirement Level | Description                                          | Example                                    |
| ------------------------- | ------ | ----------------- | ---------------------------------------------------- | ------------------------------------------ |
| `gen_ai.tool.description` | string | optional          | Description of the tool executed.                    | `"Tool returning a random number"`         |
| `gen_ai.tool.input`       | string | optional          | Input that was given to the executed tool as string. | `"{\"max\":10}"`                           |
| `gen_ai.tool.name`        | string | optional          | Name of the tool executed.                           | `"random_number"`                          |
| `gen_ai.tool.output`      | string | optional          | The output from the tool.                            | `"7"`                                      |
| `gen_ai.tool.type`        | string | optional          | The type of the tools.                               | `"function"`; `"extension"`; `"datastore"` |

#### [Example Execute Tool Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#example-execute-tool-span)

```javascript
// Example implementation for demonstration
const myAi = {
  modelProvider: "openai",
  model: "gpt-4o-mini",
  async createMessage(messages, maxTokens) {
    // AI implementation that returns tool calls
    return {
      toolCalls: [
        {
          name: "random_number",
          description: "Generate a random number",
          arguments: { max: 10 },
        },
      ],
    };
  },
};

const prompt = "Generate a random number between 0 and 10";
const messages = [{ role: "user", content: prompt }];

// First, make the AI call
const result = await Sentry.startSpan(
  { op: "gen_ai.chat", name: `chat ${myAi.model}` },
  () => myAi.createMessage(messages, 1024),
);

// Check if we should call a tool
if (result.toolCalls && result.toolCalls.length > 0) {
  const tool = result.toolCalls[0];

  await Sentry.startSpan(
    {
      op: "gen_ai.execute_tool",
      name: `execute_tool ${tool.name}`,
      attributes: {
        "gen_ai.request.model": myAi.model,
        "gen_ai.tool.type": "function",
        "gen_ai.tool.name": tool.name,
        "gen_ai.tool.description": tool.description,
        "gen_ai.tool.input": JSON.stringify(tool.arguments),
      },
    },
    async (span) => {
      // run tool (example implementation)
      const toolResult = Math.floor(Math.random() * tool.arguments.max);

      // set tool result
      span.setAttribute("gen_ai.tool.output", String(toolResult));

      return toolResult;
    },
  );
}
```

### [Handoff Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#handoff-span)

Handoff span attributes

A span that describes the handoff from one agent to another.

* The spans `op` MUST be `"gen_ai.handoff"`.
* The spans `name` SHOULD be `"handoff from {from_agent} to {to_agent}"`.
* All [Common Span Attributes](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#common-span-attributes) SHOULD be set.

#### [Example of a Handoff Span](https://docs.sentry.io/platforms/javascript/guides/solid/tracing/instrumentation/ai-agents-module-browser.md#example-of-a-handoff-span)

```javascript
// Example agent implementation for demonstration
const myAgent = {
  name: "Weather Agent",
  modelProvider: "openai",
  model: "gpt-4o-mini",
  async run() {
    // Agent implementation
    return {
      handoffTo: "Travel Agent",
      output:
        "I need to handoff to the travel agent for booking recommendations",
    };
  },
};

const otherAgent = {
  name: "Travel Agent",
  modelProvider: "openai",
  model: "gpt-4o-mini",
  async run() {
    // Other agent implementation
    return { output: "Here are some travel recommendations..." };
  },
};

// First agent execution
const result = await Sentry.startSpan(
  { op: "gen_ai.invoke_agent", name: `invoke_agent ${myAgent.name}` },
  () => myAgent.run(),
);

// Check if we should handoff to another agent
if (result.handoffTo) {
  // Create handoff span
  await Sentry.startSpan(
    {
      op: "gen_ai.handoff",
      name: `handoff from ${myAgent.name} to ${otherAgent.name}`,
      attributes: {
        "gen_ai.request.model": myAgent.model,
      },
    },
    () => {
      // the handoff span just marks the handoff
      // no actual work is done here
    },
  );

  // Execute the other agent
  await Sentry.startSpan(
    { op: "gen_ai.invoke_agent", name: `invoke_agent ${otherAgent.name}` },
    () => otherAgent.run(),
  );
}
```

Common span attributes

Some attributes are common to all AI Agents spans:

| Data Attribute          | Type   | Requirement Level | Description                                          | Example           |
| ----------------------- | ------ | ----------------- | ---------------------------------------------------- | ----------------- |
| `gen_ai.request.model`  | string | required          | The name of the AI model a request is being made to. | `"o3-mini"`       |
| `gen_ai.operation.name` | string | optional          | The name of the operation being performed.           | `"summarize"`     |
| `gen_ai.agent.name`     | string | optional          | The name of the agent this span belongs to.          | `"Weather Agent"` |
