Skip to content

Commit 67bd92c

Browse files
obostjancicobostjancic
authored
docs(ai): Add naming your agents page (#17133)
1 parent 959edf2 commit 67bd92c

File tree

6 files changed

+293
-1
lines changed

6 files changed

+293
-1
lines changed

‎docs/ai/monitoring/agents/dashboard.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ The dashboard displays the following key widgets:
3131
- **Tokens Used**: Token usage by top models
3232
- **Tool Calls**: Tool call volume and trends
3333

34+
Agents are grouped by name. If your agents show up as unnamed, see [Naming Your Agents](/ai/monitoring/agents/naming/).
35+
3436
Below these widgets is a traces table with detailed distribution information:
3537

3638
![AI Agent Trace Table](./img/trace-table-detailed-distribution.png)

‎docs/ai/monitoring/agents/getting-started.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ To start sending AI agent data to Sentry, make sure you've created a Sentry proj
2121
- [Browser (JavaScript)](/platforms/javascript/ai-agent-monitoring-browser/)
2222
- [.NET](/platforms/dotnet/tracing/instrumentation/ai-agents-module/)
2323

24+
After setting up, [name your agents](/ai/monitoring/agents/naming/) so they appear as identifiable entries in the AI Agents dashboard.
25+
2426
<Alert title="Don't see your runtime?">
2527

2628
You can also instrument AI agents manually by following our [manual instrumentation guides](/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module).

‎docs/ai/monitoring/agents/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,4 @@ To use AI Agent Monitoring, you must have an existing Sentry account and project
3131

3232
![AI Agents Monitoring Overview](./img/overview-tab.png)
3333

34-
Learn how to [set up Sentry for AI Agents](/ai/monitoring/agents/getting-started/).
34+
Learn how to [set up Sentry for AI Agents](/ai/monitoring/agents/getting-started/) and [name your agents](/ai/monitoring/agents/naming/) so they're identifiable in the dashboard.

‎docs/ai/monitoring/agents/naming.mdx‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
---
2+
title: Naming Your Agents
3+
sidebar_order: 12
4+
description: "Set the agent name so Sentry can identify, filter, and alert on individual agents in the AI Agents Dashboard."
5+
keywords:
6+
- AI agents
7+
- agent name
8+
- gen_ai.agent.name
9+
- agent monitoring
10+
- agent identification
11+
---
12+
13+
Sentry uses the `gen_ai.agent.name` span attribute to identify agents in the [AI Agents Dashboard](/ai/monitoring/agents/dashboard/). Without a name, you won't be able to filter for a specific agent, group results by agent, or set up alerts for individual agents.
14+
15+
## Quick Reference
16+
17+
| Framework | Platform | How to Name |
18+
| ----------------------- | -------- | ------------------------------------------------------------------ |
19+
| OpenAI Agents SDK | Python | `Agent(name="...")` |
20+
| Pydantic AI | Python | `Agent(..., name="...")` |
21+
| LangChain | Python | `create_agent(model, tools, name="...")` |
22+
| LangGraph | Python | `.compile(name="...")` or `create_react_agent(..., name="...")` |
23+
| Vercel AI SDK | JS | `experimental_telemetry: { functionId: "..." }` |
24+
| LangGraph | JS | `.compile({ name: "..." })` or `createReactAgent({ name: "..." })` |
25+
| LangChain | JS | `createAgent({ name: "..." })` |
26+
| Mastra | JS | `Agent({ id: "...", name: "..." })` |
27+
| .NET (M.E.AI) | .NET | `options.Experimental.AgentName = "..."` |
28+
| Other / raw LLM clients | Any | [Manual instrumentation](#manual-instrumentation) |
29+
30+
## Framework Integrations
31+
32+
Most AI agent frameworks have a built-in name parameter that Sentry picks up automatically.
33+
34+
### Python
35+
36+
#### OpenAI Agents SDK
37+
38+
The `name` parameter is required by the SDK. Sentry reads it automatically.
39+
40+
```python
41+
from openai import agents
42+
43+
agent = agents.Agent(
44+
name="Weather Agent",
45+
instructions="You are a helpful weather assistant.",
46+
model="gpt-4o-mini",
47+
)
48+
```
49+
50+
<PlatformLink platform="python" to="/integrations/openai-agents/">
51+
OpenAI Agents integration docs
52+
</PlatformLink>
53+
54+
#### Pydantic AI
55+
56+
Pass `name` when creating the agent.
57+
58+
```python
59+
from pydantic_ai import Agent
60+
61+
agent = Agent(
62+
"openai:gpt-4o-mini",
63+
name="Customer Support Agent",
64+
system_prompt="You help customers with their questions.",
65+
)
66+
```
67+
68+
<PlatformLink platform="python" to="/integrations/pydantic-ai/">
69+
Pydantic AI integration docs
70+
</PlatformLink>
71+
72+
#### LangChain
73+
74+
Pass `name` to `create_agent`.
75+
76+
```python
77+
from langchain.agents import create_agent
78+
from langchain.chat_models import init_chat_model
79+
80+
model = init_chat_model("gpt-4o-mini", model_provider="openai")
81+
agent = create_agent(model, tools, name="dice_agent")
82+
```
83+
84+
<PlatformLink platform="python" to="/integrations/langchain/">
85+
LangChain integration docs
86+
</PlatformLink>
87+
88+
#### LangGraph
89+
90+
Pass `name` to `StateGraph.compile()` or `create_react_agent`.
91+
92+
```python
93+
from langgraph.graph import StateGraph
94+
95+
graph = StateGraph(AgentState)
96+
# ... add nodes and edges ...
97+
agent = graph.compile(name="dice_agent")
98+
```
99+
100+
Or with the prebuilt helper:
101+
102+
```python
103+
from langgraph.prebuilt import create_react_agent
104+
105+
agent = create_react_agent(model, tools, name="dice_agent")
106+
```
107+
108+
<PlatformLink platform="python" to="/integrations/langgraph/">
109+
LangGraph integration docs
110+
</PlatformLink>
111+
112+
### JavaScript / Node.js
113+
114+
#### Vercel AI SDK
115+
116+
Vercel AI SDK doesn't have a dedicated agent name field. Instead, set `functionId` in `experimental_telemetry` — Sentry uses this as the agent identifier.
117+
118+
```javascript
119+
import { generateText } from "ai";
120+
import { openai } from "@ai-sdk/openai";
121+
122+
const result = await generateText({
123+
model: openai("gpt-4o"),
124+
prompt: "Tell me a joke",
125+
experimental_telemetry: {
126+
isEnabled: true,
127+
functionId: "joke_agent",
128+
},
129+
});
130+
```
131+
132+
<PlatformLink
133+
platform="javascript.node"
134+
to="/configuration/integrations/vercelai/"
135+
>
136+
Vercel AI SDK integration docs
137+
</PlatformLink>
138+
139+
#### LangGraph
140+
141+
Pass `name` to `.compile()` or `createReactAgent`.
142+
143+
```javascript
144+
import { StateGraph } from "@langchain/langgraph";
145+
146+
const graph = new StateGraph(AgentState);
147+
// ... add nodes and edges ...
148+
const agent = graph.compile({ name: "weather_agent" });
149+
```
150+
151+
Or with the prebuilt helper:
152+
153+
```javascript
154+
import { createReactAgent } from "@langchain/langgraph/prebuilt";
155+
156+
const agent = createReactAgent({
157+
llm: model,
158+
tools: [getWeather],
159+
name: "weather_agent",
160+
});
161+
```
162+
163+
<PlatformLink
164+
platform="javascript.node"
165+
to="/configuration/integrations/langgraph/"
166+
>
167+
LangGraph integration docs
168+
</PlatformLink>
169+
170+
#### LangChain
171+
172+
Pass `name` to `createAgent`.
173+
174+
```javascript
175+
import { createAgent } from "langchain";
176+
177+
const agent = createAgent({
178+
llm: model,
179+
tools: [getWeather],
180+
name: "weather_agent",
181+
});
182+
```
183+
184+
<PlatformLink
185+
platform="javascript.node"
186+
to="/configuration/integrations/langchain/"
187+
>
188+
LangChain integration docs
189+
</PlatformLink>
190+
191+
#### Mastra
192+
193+
Mastra requires both `id` and `name` on the agent definition. The Mastra exporter sends the name to Sentry automatically.
194+
195+
```javascript
196+
const agent = new Agent({
197+
id: "weather-agent",
198+
name: "Weather Agent",
199+
instructions: "You are a helpful weather assistant.",
200+
model: "openai/gpt-4o",
201+
});
202+
```
203+
204+
<PlatformLink platform="javascript.node" to="/ai-agent-monitoring/mastra/">
205+
Mastra integration docs
206+
</PlatformLink>
207+
208+
### .NET
209+
210+
Set `AgentName` in the Sentry AI instrumentation options.
211+
212+
```csharp
213+
var client = new OpenAI.Chat.ChatClient("gpt-4o-mini", apiKey)
214+
.AsIChatClient()
215+
.AddSentry(options =>
216+
{
217+
options.Experimental.AgentName = "WeatherAgent";
218+
});
219+
```
220+
221+
See the [.NET AI Agents instrumentation docs](/platforms/dotnet/tracing/instrumentation/ai-agents-module/) for the full setup.
222+
223+
## Manual Instrumentation
224+
225+
For frameworks without built-in naming, or when using raw LLM clients (OpenAI, Anthropic, Google GenAI, LiteLLM), wrap your agent logic in an `invoke_agent` span and set `gen_ai.agent.name`.
226+
227+
### Python
228+
229+
```python
230+
import sentry_sdk
231+
232+
with sentry_sdk.start_span(
233+
op="gen_ai.invoke_agent",
234+
name="invoke_agent Weather Agent",
235+
) as span:
236+
span.set_data("gen_ai.agent.name", "Weather Agent")
237+
span.set_data("gen_ai.request.model", "gpt-4o-mini")
238+
239+
result = my_agent.run()
240+
241+
span.set_data("gen_ai.usage.input_tokens", result.usage.input_tokens)
242+
span.set_data("gen_ai.usage.output_tokens", result.usage.output_tokens)
243+
```
244+
245+
See [Python manual instrumentation](/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module/#invoke-agent-span) for full span attributes.
246+
247+
### JavaScript
248+
249+
```javascript
250+
import * as Sentry from "@sentry/node";
251+
252+
await Sentry.startSpan(
253+
{
254+
op: "gen_ai.invoke_agent",
255+
name: "invoke_agent Weather Agent",
256+
attributes: {
257+
"gen_ai.agent.name": "Weather Agent",
258+
"gen_ai.request.model": "gpt-4o-mini",
259+
},
260+
},
261+
async (span) => {
262+
const result = await myAgent.run();
263+
264+
span.setAttribute("gen_ai.usage.input_tokens", result.usage.inputTokens);
265+
span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
266+
}
267+
);
268+
```
269+
270+
See [JavaScript manual instrumentation](/platforms/javascript/guides/node/ai-agent-monitoring/#invoke-agent-span) for full span attributes.
271+
272+
## Next Steps
273+
274+
- [AI Agents Dashboard](/ai/monitoring/agents/dashboard/) — view and filter agents by name
275+
- [Data Privacy](/ai/monitoring/agents/privacy/) — control what data is sent to Sentry
276+
- [Model Costs](/ai/monitoring/agents/costs/) — track token usage and estimated costs

‎docs/platforms/javascript/common/ai-agent-monitoring/index.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,12 @@ await Sentry.startSpan(
226226

227227
### Invoke Agent Span
228228

229+
<Alert>
230+
231+
For a complete guide on naming agents across all supported frameworks, see [Naming Your Agents](/ai/monitoring/agents/naming/).
232+
233+
</Alert>
234+
229235
<SplitLayout>
230236
<SplitSection>
231237
<SplitSectionText>

‎docs/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,12 @@ This span represents the execution of an AI agent, capturing the full lifecycle
6868
<Include name="tracing/ai-agents-module/invoke-agent-span" />
6969
</Expandable>
7070

71+
<Alert>
72+
73+
For a complete guide on naming agents across all supported frameworks, see [Naming Your Agents](/ai/monitoring/agents/naming/).
74+
75+
</Alert>
76+
7177
#### Example of an Invoke Agent Span:
7278

7379
```python

0 commit comments

Comments
 (0)