Skip to content

[gen-ai] expand invoke_agent span documentation beyond remote agents #2881

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+70 −23
Open

[gen-ai] expand invoke_agent span documentation beyond remote agents #2881

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2eb4f57
[gen-ai] expand invoke_agent span documentation beyond remote agents
yiyuan-he Oct 6, 2025
53792ad
address pr comments
yiyuan-he Oct 8, 2025
7942c44
Update model/gen-ai/spans.yaml
yiyuan-he Oct 15, 2025
160856b
Regenerate markdown for GenAI agent spans
yiyuan-he Oct 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/main.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: gen-ai

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: "`invoke_agent` spans now include span kind guidance (CLIENT/INTERNAL/SERVER) and clarify when `server.*` attributes should be set."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about following?

s/span kind guidance (CLIENT/INTERNAL/SERVER)/span kind (CLIENT/INTERNAL/SERVER) guidance

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion! Updated to be "span kind (CLIENT/INTERNAL/SERVER) guidance"


# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [2837]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
11 changes: 9 additions & 2 deletions docs/gen-ai/gen-ai-agent-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,14 +178,21 @@ Instrumentations SHOULD document the list of errors they report.

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Describes GenAI agent invocation and is usually applicable when working with remote agent services.
Describes GenAI agent invocation.

The `gen_ai.operation.name` SHOULD be `invoke_agent`.
The **span name** SHOULD be `invoke_agent {gen_ai.agent.name}` if `gen_ai.agent.name` is readily available.
When `gen_ai.agent.name` is not available, it SHOULD be `invoke_agent`.
Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format.

**Span kind** SHOULD be `CLIENT`.
**Span kind** SHOULD be `CLIENT` and MAY be set to `INTERNAL` on spans representing
invocation of agents running in the same process or `SERVER` when instrumenting
the agent service itself.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Server kind seems to be a step too far and there is a clear pattern of splitting the definition given that the attributes change.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point - I've removed the SERVER span kind references from this PR for now. Seems like this case will need further discussion and can be addressed in a follow-up.

It's RECOMMENDED to use `CLIENT` kind when the agent being instrumented usually runs
in a different process than its caller or when the agent invocation happens over
instrumented protocol such as HTTP.

`server.address` and `server.port` attributes SHOULD be set when span kind is `CLIENT`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be defined via the yaml model ie note on the requirement level.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks - moved to the yaml model as conditionally required attributes.


**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.

Expand Down
12 changes: 10 additions & 2 deletions model/gen-ai/spans.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,13 +252,21 @@ groups:
stability: development
span_kind: client
brief: >
Describes GenAI agent invocation and is usually applicable when working
with remote agent services.
Describes GenAI agent invocation.
note: |
The `gen_ai.operation.name` SHOULD be `invoke_agent`.
The **span name** SHOULD be `invoke_agent {gen_ai.agent.name}` if `gen_ai.agent.name` is readily available.
When `gen_ai.agent.name` is not available, it SHOULD be `invoke_agent`.
Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format.

**Span kind** SHOULD be `CLIENT` and MAY be set to `INTERNAL` on spans representing
invocation of agents running in the same process or `SERVER` when instrumenting
the agent service itself.
It's RECOMMENDED to use `CLIENT` kind when the agent being instrumented usually runs
in a different process than its caller or when the agent invocation happens over
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please add more clarification when to use different span kind, like what you clarified

CLIENT: For remote agent services (OpenAI Assistants API, AWS Bedrock)
INTERNAL: For in-process agents (LangChain, CrewAI agents)
SERVER: For instrumenting the agent service itself

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated documentation note section with examples

instrumented protocol such as HTTP.

`server.address` and `server.port` attributes SHOULD be set when span kind is `CLIENT`.
extends: attributes.gen_ai.inference.client
attributes:
- ref: gen_ai.provider.name
Expand Down
Loading