Manual Instrumentation

── invoke_agent My Agent          (gen_ai.invoke_agent)
   ├── chat gpt-4o                (gen_ai.chat)         ← 1st LLM call
   ├── execute_tool get_weather   (gen_ai.execute_tool)  ← tool run
   ├── chat gpt-4o                (gen_ai.chat)         ← 2nd LLM call
   └── ...

const messages = [
  { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] },
];
const tools = [
  { name: "get_weather", description: "Get weather for a city" },
];

await Sentry.startSpan(
  {
    op: "gen_ai.chat",
    name: "chat o3-mini",
    attributes: {
      "gen_ai.operation.name": "chat",
      "gen_ai.request.model": "o3-mini",
      "gen_ai.provider.name": "openai",
      "gen_ai.agent.name": "Weather Agent", // when this call is under an agent
      "gen_ai.system_instructions": "You are a helpful assistant.",
      "gen_ai.tool.definitions": JSON.stringify(tools),
      "gen_ai.input.messages": JSON.stringify(messages),
    },
  },
  async (span) => {
    // Call your model provider; map its response into span attributes below
    const result = await yourLLMClient.chat({
      model: "o3-mini",
      messages,
    });

    span.setAttributes({
      "gen_ai.response.model": result.model,
      "gen_ai.response.id": result.id,
      "gen_ai.output.messages": JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: result.text }],
        },
      ]),
      "gen_ai.response.finish_reasons": JSON.stringify([
        result.finishReason,
      ]),
      "gen_ai.usage.input_tokens": result.usage.inputTokens,
      "gen_ai.usage.output_tokens": result.usage.outputTokens,
    });
    // If the provider reports cached tokens, record them as a subset of input tokens
    if (result.usage.cachedInputTokens != null) {
      span.setAttribute(
        "gen_ai.usage.cache_read.input_tokens",
        result.usage.cachedInputTokens,
      );
    }
    return result;
  },
);

span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        { type: "reasoning", content: "6 times 7 is 42." },
        { type: "text", content: "The answer is 42." },
      ],
    },
  ]),
);
span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
// Reasoning tokens are a subset of output tokens
span.setAttribute(
  "gen_ai.usage.reasoning.output_tokens",
  result.usage.reasoningTokens,
);

// Model asked to call a tool
span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        {
          type: "tool_call",
          id: "call_abc",
          name: "get_weather",
          arguments: { location: "Paris" },
        },
      ],
    },
  ]),
);

// Later chat span: tool result fed back to the model
const inputWithTool = [
  {
    role: "user",
    parts: [{ type: "text", content: "Weather in Paris?" }],
  },
  {
    role: "assistant",
    parts: [
      {
        type: "tool_call",
        id: "call_abc",
        name: "get_weather",
        arguments: { location: "Paris" },
      },
    ],
  },
  {
    role: "tool",
    parts: [
      {
        type: "tool_call_response",
        id: "call_abc",
        name: "get_weather",
        content: '{"temp_c": 18}',
      },
    ],
  },
];
span.setAttribute("gen_ai.input.messages", JSON.stringify(inputWithTool));

const messages = [
  {
    role: "user",
    parts: [{ type: "text", content: "What's the weather in Paris?" }],
  },
];
const tools = [
  { name: "get_weather", description: "Get weather for a city" },
];

await Sentry.startSpan(
  {
    op: "gen_ai.invoke_agent",
    name: "invoke_agent Weather Agent",
    attributes: {
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.name": "Weather Agent",
      "gen_ai.provider.name": "openai",
      "gen_ai.request.model": "o3-mini",
      "gen_ai.system_instructions": "You are a weather assistant.",
      "gen_ai.tool.definitions": JSON.stringify(tools),
      "gen_ai.input.messages": JSON.stringify(messages),
    },
  },
  async (span) => {
    // myAgent is your agent runner; expect { output, usage: { inputTokens, outputTokens } }
    const result = await myAgent.run();

    span.setAttribute(
      "gen_ai.output.messages",
      JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: String(result.output) }],
        },
      ]),
    );
    span.setAttribute(
      "gen_ai.usage.input_tokens",
      result.usage.inputTokens,
    );
    span.setAttribute(
      "gen_ai.usage.output_tokens",
      result.usage.outputTokens,
    );
    return result;
  },
);

await Sentry.startSpan(
  {
    op: "gen_ai.execute_tool",
    name: "execute_tool get_weather",
    attributes: {
      "gen_ai.operation.name": "execute_tool",
      "gen_ai.tool.name": "get_weather",
      "gen_ai.tool.description": "Get weather for a city",
      "gen_ai.tool.call.arguments": JSON.stringify({ location: "Paris" }),
    },
  },
  async (span) => {
    try {
      const result = await getWeather({ location: "Paris" });
      span.setAttribute("gen_ai.tool.call.result", JSON.stringify(result));
      return result;
    } catch (error) {
      span.setStatus({ code: 2, message: "internal_error" });
      span.setAttribute(
        "error.type",
        error instanceof Error ? error.constructor.name : "Error",
      );
      throw error;
    }
  },
);

async function callLLMStreaming(model, messages) {
  const span = Sentry.startInactiveSpan({
    name: `chat ${model}`,
    op: "gen_ai.chat",
    attributes: {
      "gen_ai.operation.name": "chat",
      "gen_ai.request.model": model,
      "gen_ai.input.messages": JSON.stringify(messages),
    },
  });

  try {
    const stream = await Sentry.withActiveSpan(span, () =>
      yourLLMClient.stream({ model, messages }),
    );

    // Accumulate from chunk events — stream "end" has no payload
    let text = "";
    let usage = { inputTokens: 0, outputTokens: 0 };
    let responseModel = model;

    stream.on("data", (chunk) => {
      // Map chunk fields to your provider's shape
      if (chunk.text) {
        text += chunk.text;
      }
      if (chunk.usage) {
        usage = chunk.usage;
      }
      if (chunk.model) {
        responseModel = chunk.model;
      }
    });

    stream.on("end", () => {
      span.setAttribute(
        "gen_ai.output.messages",
        JSON.stringify([
          {
            role: "assistant",
            parts: [{ type: "text", content: text }],
          },
        ]),
      );
      span.setAttribute("gen_ai.usage.input_tokens", usage.inputTokens);
      span.setAttribute("gen_ai.usage.output_tokens", usage.outputTokens);
      span.setAttribute("gen_ai.response.model", responseModel);
      span.setAttribute("gen_ai.response.streaming", true);
      span.end();
    });

    stream.on("error", (error) => {
      span.setStatus({ code: 2, message: "internal_error" });
      span.setAttribute(
        "error.type",
        error instanceof Error ? error.constructor.name : "Error",
      );
      span.end();
    });
    return stream;
  } catch (error) {
    span.setStatus({ code: 2, message: "internal_error" });
    span.setAttribute(
      "error.type",
      error instanceof Error ? error.constructor.name : "Error",
    );
    span.end();
    throw error;
  }
}