Browser AI Monitoring

Learn how to manually instrument AI agents in browser applications.

With Sentry AI Agent Monitoring, 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.

Before setting up AI Agent Monitoring, ensure you have tracing enabled in your Sentry configuration.

For supported 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.

Supported libraries:

Each integration page includes browser-specific examples with options like recordInputs and recordOutputs.

Copied
import * as Sentry from "___SDK_PACKAGE___";
import OpenAI from "openai";

const client = Sentry.instrumentOpenAiClient(
  new OpenAI({ apiKey: "...", dangerouslyAllowBrowser: true }),
  {
    recordInputs: true,
    recordOutputs: true,
  },
);

// All calls are now instrumented
const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});

If you're using a library that Sentry doesn't provide helpers for, you can manually create spans. For your data to show up in AI Agents Insights, spans must have well-defined names and data attributes.

This span represents the execution of an AI agent, capturing the full lifecycle from receiving a task to producing a final response.

Key attributes:

  • gen_ai.agent.name — The agent's name (e.g., "Weather Agent")
  • gen_ai.request.model — The underlying model used
  • gen_ai.response.text — The agent's final output
  • gen_ai.usage.input_tokens / output_tokens — Total token counts
Copied
// 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
    span.setAttribute(
      "gen_ai.response.text",
      JSON.stringify([result.output]),
    );

    // set token usage
    span.setAttribute(
      "gen_ai.usage.input_tokens",
      result.usage.inputTokens,
    );
    span.setAttribute(
      "gen_ai.usage.output_tokens",
      result.usage.outputTokens,
    );

    return result;
  },
);
All 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 SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Data AttributeTypeRequirement LevelDescriptionExample
gen_ai.request.available_toolsstringoptionalList of objects describing the available tools. [0]"[{\"name\": \"random_number\", \"description\": \"...\"}, {\"name\": \"query_db\", \"description\": \"...\"}]"
gen_ai.request.frequency_penaltyfloatoptionalModel configuration parameter.0.5
gen_ai.request.max_tokensintoptionalModel configuration parameter.500
gen_ai.request.messagesstringoptionalList of objects describing the messages (prompts) sent to the LLM [0], [1]"[{\"role\": \"system\", \"content\": [{...}]}, {\"role\": \"system\", \"content\": [{...}]}]"
gen_ai.request.presence_penaltyfloatoptionalModel configuration parameter.0.5
gen_ai.request.temperaturefloatoptionalModel configuration parameter.0.1
gen_ai.request.top_pfloatoptionalModel configuration parameter.0.7
gen_ai.response.tool_callsstringoptionalThe tool calls in the model’s response. [0]"[{\"name\": \"random_number\", \"type\": \"function_call\", \"arguments\": \"...\"}]"
gen_ai.response.textstringoptionalThe 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.cache_writeintoptionalThe number of tokens written to the cache when processing the AI input (prompt).100
gen_ai.usage.input_tokens.cachedintoptionalThe number of cached tokens used in the AI input (prompt)50
gen_ai.usage.input_tokensintoptionalThe number of tokens used in the AI input (prompt).10
gen_ai.usage.output_tokens.reasoningintoptionalThe number of tokens used for reasoning.30
gen_ai.usage.output_tokensintoptionalThe number of tokens used in the AI response.100
gen_ai.usage.total_tokensintoptionalThe 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.

This span represents a chat or completion request to an LLM, capturing the messages, model configuration, and response.

Key attributes:

  • gen_ai.request.model — The model name (required)
  • gen_ai.request.messages — Chat messages sent to the LLM
  • gen_ai.request.max_tokens — Token limit for the response
  • gen_ai.response.text — The model's response
Copied
// Example AI 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 messages = [{ role: "user", content: "Tell me a joke" }];

    // 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,
    );

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

    // set response
    span.setAttribute(
      "gen_ai.response.text",
      JSON.stringify([result.output]),
    );

    // set token usage
    span.setAttribute(
      "gen_ai.usage.input_tokens",
      result.usage.inputTokens,
    );
    span.setAttribute(
      "gen_ai.usage.output_tokens",
      result.usage.outputTokens,
    );

    return result;
  },
);
All 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 SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Data AttributeTypeRequirement LevelDescriptionExample
gen_ai.request.available_toolsstringoptionalList of objects describing the available tools. [0]"[{\"name\": \"random_number\", \"description\": \"...\"}, {\"name\": \"query_db\", \"description\": \"...\"}]"
gen_ai.request.frequency_penaltyfloatoptionalModel configuration parameter.0.5
gen_ai.request.max_tokensintoptionalModel configuration parameter.500
gen_ai.request.messagesstringoptionalList of objects describing the messages (prompts) sent to the LLM [0], [1]"[{\"role\": \"system\", \"content\": [{...}]}, {\"role\": \"system\", \"content\": [{...}]}]"
gen_ai.request.presence_penaltyfloatoptionalModel configuration parameter.0.5
gen_ai.request.temperaturefloatoptionalModel configuration parameter.0.1
gen_ai.request.top_pfloatoptionalModel configuration parameter.0.7
gen_ai.response.tool_callsstringoptionalThe tool calls in the model's response. [0]"[{\"name\": \"random_number\", \"type\": \"function_call\", \"arguments\": \"...\"}]"
gen_ai.response.textstringoptionalThe 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.cache_writeintoptionalThe number of tokens written to the cache when processing the AI input (prompt).100
gen_ai.usage.input_tokens.cachedintoptionalThe number of cached tokens used in the AI input (prompt)50
gen_ai.usage.input_tokensintoptionalThe number of tokens used in the AI input (prompt).10
gen_ai.usage.output_tokens.reasoningintoptionalThe number of tokens used for reasoning.30
gen_ai.usage.output_tokensintoptionalThe number of tokens used in the AI response.100
gen_ai.usage.total_tokensintoptionalThe 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.

This span represents the execution of a tool or function that was requested by an AI model, including the input arguments and resulting output.

Key attributes:

  • gen_ai.tool.name — The tool's name (e.g., "random_number")
  • gen_ai.tool.description — Description of what the tool does
  • gen_ai.tool.input — The arguments passed to the tool
  • gen_ai.tool.output — The tool's return value
Copied
// Example AI 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 messages = [
  { role: "user", content: "Generate a random number between 0 and 10" },
];

// 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;
    },
  );
}
All 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 SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Data AttributeTypeRequirement LevelDescriptionExample
gen_ai.tool.descriptionstringoptionalDescription of the tool executed."Tool returning a random number"
gen_ai.tool.inputstringoptionalInput that was given to the executed tool as string."{\"max\":10}"
gen_ai.tool.namestringoptionalName of the tool executed."random_number"
gen_ai.tool.outputstringoptionalThe output from the tool."7"
gen_ai.tool.typestringoptionalThe type of the tools."function"; "extension"; "datastore"

This span marks the transition of control from one agent to another, typically when the current agent determines another agent is better suited to handle the task.

Requirements:

  • op must be "gen_ai.handoff"
  • name should follow the pattern "handoff from {source} to {target}"
  • All Common Span Attributes should be set

The handoff span itself has no body — it just marks the transition point before the target agent starts.

Copied
// Example agent implementations 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(),
  );
}

Some attributes are common to all AI Agents spans:

Data AttributeTypeRequirement LevelDescriptionExample
gen_ai.request.modelstringrequiredThe name of the AI model a request is being made to."o3-mini"
gen_ai.operation.namestringoptionalThe name of the operation being performed."summarize"
gen_ai.agent.namestringoptionalThe name of the agent this span belongs to."Weather Agent"
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").