Skip to content

Commit fb500fb

Browse files
obostjancicobostjancic
committed
docs(ai): Add naming your agents page
1 parent 7fd5c0a commit fb500fb

File tree

6 files changed

+281
-1
lines changed

6 files changed

+281
-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: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
---
2+
title: Naming Your Agents
3+
sidebar_order: 5
4+
description: "Learn how to name your AI agents so they appear as identifiable entries in Sentry's AI Agent Monitoring dashboards."
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 | `create_react_agent(model, tools, name="...")` |
23+
| Vercel AI SDK | JS | `experimental_telemetry: { functionId: "..." }` |
24+
| LangGraph | JS | `createReactAgent({ name: "..." })` or `.compile({ 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-Specific Naming
31+
32+
Most AI agent frameworks have a built-in name parameter that Sentry picks up automatically through its integrations.
33+
34+
### Python
35+
36+
#### OpenAI Agents SDK
37+
38+
The `name` parameter is required by the SDK and 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+
Use the `create_agent` function with a `name` parameter.
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+
Use the `create_react_agent` function with a `name` parameter.
91+
92+
```python
93+
from langgraph.prebuilt import create_react_agent
94+
from langchain.chat_models import init_chat_model
95+
96+
model = init_chat_model("gpt-4o-mini", model_provider="openai")
97+
agent = create_react_agent(model, tools, name="dice_agent")
98+
```
99+
100+
<PlatformLink platform="python" to="/integrations/langgraph/">
101+
LangGraph integration docs
102+
</PlatformLink>
103+
104+
### JavaScript / Node.js
105+
106+
#### Vercel AI SDK
107+
108+
Vercel AI SDK uses `functionId` inside `experimental_telemetry` to identify agents.
109+
110+
```javascript
111+
import { generateText } from "ai";
112+
import { openai } from "@ai-sdk/openai";
113+
114+
const result = await generateText({
115+
model: openai("gpt-4o"),
116+
prompt: "Tell me a joke",
117+
experimental_telemetry: {
118+
isEnabled: true,
119+
functionId: "joke_agent",
120+
},
121+
});
122+
```
123+
124+
<PlatformLink
125+
platform="javascript.node"
126+
to="/configuration/integrations/vercelai/"
127+
>
128+
Vercel AI SDK integration docs
129+
</PlatformLink>
130+
131+
#### LangGraph
132+
133+
Pass `name` to `createReactAgent` or to `.compile()`.
134+
135+
```javascript
136+
import { createReactAgent } from "@langchain/langgraph/prebuilt";
137+
138+
const agent = createReactAgent({
139+
llm: model,
140+
tools: [getWeather],
141+
name: "weather_agent",
142+
});
143+
```
144+
145+
Or when using `StateGraph` directly:
146+
147+
```javascript
148+
const graph = agent.compile({ name: "weather_agent" });
149+
```
150+
151+
<PlatformLink
152+
platform="javascript.node"
153+
to="/configuration/integrations/langgraph/"
154+
>
155+
LangGraph integration docs
156+
</PlatformLink>
157+
158+
#### LangChain
159+
160+
Use the new `createAgent` function with a `name` parameter.
161+
162+
```javascript
163+
import { createAgent } from "langchain";
164+
165+
const agent = createAgent({
166+
llm: model,
167+
tools: [getWeather],
168+
name: "weather_agent",
169+
});
170+
```
171+
172+
<PlatformLink
173+
platform="javascript.node"
174+
to="/configuration/integrations/langchain/"
175+
>
176+
LangChain integration docs
177+
</PlatformLink>
178+
179+
#### Mastra
180+
181+
Mastra requires both `id` and `name` on the agent definition. Sentry reads the name automatically through the Mastra exporter.
182+
183+
```javascript
184+
const agent = new Agent({
185+
id: "weather-agent",
186+
name: "Weather Agent",
187+
instructions: "You are a helpful weather assistant.",
188+
model: "openai/gpt-4o",
189+
});
190+
```
191+
192+
<PlatformLink platform="javascript.node" to="/ai-agent-monitoring/mastra/">
193+
Mastra integration docs
194+
</PlatformLink>
195+
196+
### .NET
197+
198+
Set `AgentName` in the Sentry AI instrumentation options.
199+
200+
```csharp
201+
var client = new OpenAI.Chat.ChatClient("gpt-4o-mini", apiKey)
202+
.AsIChatClient()
203+
.AddSentry(options =>
204+
{
205+
options.Experimental.AgentName = "WeatherAgent";
206+
});
207+
```
208+
209+
See the [.NET AI Agents instrumentation docs](/platforms/dotnet/tracing/instrumentation/ai-agents-module/) for the full setup.
210+
211+
## Manual Instrumentation
212+
213+
If your framework doesn't have built-in naming support, or you're using raw LLM clients (OpenAI, Anthropic, Google GenAI, LiteLLM), wrap your agent logic in an `invoke_agent` span and set the `gen_ai.agent.name` attribute.
214+
215+
### Python
216+
217+
```python
218+
import sentry_sdk
219+
220+
with sentry_sdk.start_span(
221+
op="gen_ai.invoke_agent",
222+
name="invoke_agent Weather Agent",
223+
) as span:
224+
span.set_data("gen_ai.agent.name", "Weather Agent")
225+
span.set_data("gen_ai.request.model", "gpt-4o-mini")
226+
227+
result = my_agent.run()
228+
229+
span.set_data("gen_ai.usage.input_tokens", result.usage.input_tokens)
230+
span.set_data("gen_ai.usage.output_tokens", result.usage.output_tokens)
231+
```
232+
233+
See [Python manual instrumentation](/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module/#invoke-agent-span) for full span attributes.
234+
235+
### JavaScript
236+
237+
```javascript
238+
import * as Sentry from "@sentry/node";
239+
240+
await Sentry.startSpan(
241+
{
242+
op: "gen_ai.invoke_agent",
243+
name: "invoke_agent Weather Agent",
244+
attributes: {
245+
"gen_ai.agent.name": "Weather Agent",
246+
"gen_ai.request.model": "gpt-4o-mini",
247+
},
248+
},
249+
async (span) => {
250+
const result = await myAgent.run();
251+
252+
span.setAttribute("gen_ai.usage.input_tokens", result.usage.inputTokens);
253+
span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
254+
}
255+
);
256+
```
257+
258+
See [JavaScript manual instrumentation](/platforms/javascript/guides/node/ai-agent-monitoring/#invoke-agent-span) for full span attributes.
259+
260+
## Next Steps
261+
262+
- [AI Agents Dashboard](/ai/monitoring/agents/dashboard/) — see your named agents in action
263+
- [Data Privacy](/ai/monitoring/agents/privacy/) — control what data is sent to Sentry
264+
- [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+
<Note>
230+
231+
For a complete guide on naming agents across all supported frameworks, see [Naming Your Agents](/ai/monitoring/agents/naming/).
232+
233+
</Note>
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+
<Note>
72+
73+
For a complete guide on naming agents across all supported frameworks, see [Naming Your Agents](/ai/monitoring/agents/naming/).
74+
75+
</Note>
76+
7177
#### Example of an Invoke Agent Span:
7278

7379
```python

0 commit comments

Comments
 (0)