feat(js): Add ai agents module manual instrumentation docs for js (#14190)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

## DESCRIBE YOUR PR

Adds docs for instrumenting manually ai agents with javascript for the
agent monitoring insights module. To reduce duplication, I extracted
snippets out into their own includes.

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [x] Urgent deadline (GA date, etc.): GA was released Thurs June 26, so
these docs need to go out asap for that
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [ ] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

<!-- Sentry employees and contractors can delete or ignore this section.
-->

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

---------

Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>

Author: AbhiPrasad

docs/platforms/javascript/common/tracing/instrumentation/ai-agents-module.mdx

@@ -0,0 +1,283 @@
+---
+title: Instrument AI Agents
+sidebar_order: 500
+description: "Learn how to manually instrument your code to use Sentry's Agents module."
+---
+
+With <Link to="/product/insights/agents/dashboard/">Sentry AI Agent Monitoring</Link>, 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 with JavaScript, you'll need to first <PlatformLink to="/tracing/">set up tracing</PlatformLink>. Once this is done, the JavaScript SDK will automatically instrument AI agents created with supported libraries. If that doesn't fit your use case, you can use custom instrumentation described below.
+
+## Automatic Instrumentation
+
+The JavaScript SDK supports automatic instrumentation for some AI libraries. We recommend adding their integrations to your Sentry configuration to automatically capture spans for AI agents.
+
+- <PlatformLink to="/configuration/integrations/vercelai/">
+    Vercel AI SDK
+  </PlatformLink>
+
+## Manual Instrumentation
+
+If you're using a library that Sentry does not automatically instrument, you can manually instrument your code to capture spans. For your AI agents data to show up in the Sentry [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/agents/), two spans must be created and have well-defined names and data attributes. See below.
+
+## Spans
+
+### Invoke Agent Span
+
+<Include name="tracing/ai-agents-module/invoke-agent-span" />
+
+#### Example of an Invoke Agent Span:
+
+```javascript
+// some example agent implementation for demonstration
+const myAgent = {
+  name: "Weather Agent",
+  modelProvider: "openai",
+  model: "o3-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.system": myAgent.modelProvider,
+      "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
+
+<Include name="tracing/ai-agents-module/ai-client-span" />
+
+#### Example AI Client Span
+
+```javascript
+// some example implementation for demonstration
+const myAi = {
+  modelProvider: "openai",
+  model: "o3-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.system": myAi.modelProvider,
+      "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
+
+<Include name="tracing/ai-agents-module/execute-tool-span" />
+
+#### Example Execute Tool Span
+
+```javascript
+// some example implementation for demonstration
+const myAi = {
+  modelProvider: "openai",
+  model: "o3-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: `gen_ai.execute_tool ${tool.name}`,
+      attributes: {
+        "gen_ai.system": myAi.modelProvider,
+        "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
+
+<Include name="tracing/ai-agents-module/handoff-span" />
+
+#### Example of a Handoff Span
+
+```javascript
+// some example agent implementation for demonstration
+const myAgent = {
+  name: "Weather Agent",
+  modelProvider: "openai",
+  model: "o3-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: "o3-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.system": myAgent.modelProvider,
+        "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
+
+<Include name="tracing/ai-agents-module/common-span-attributes" />