Skip to content

Split invoke_agent into separate client and internal spans, and split attributes from inference hierarchy#3514

Merged
lmolkova merged 7 commits intoopen-telemetry:mainfrom
trask:split-invoke-agent-from-inference
Apr 3, 2026
Merged

Split invoke_agent into separate client and internal spans, and split attributes from inference hierarchy#3514
lmolkova merged 7 commits intoopen-telemetry:mainfrom
trask:split-invoke-agent-from-inference

Conversation

@trask
Copy link
Copy Markdown
Member

@trask trask commented Mar 6, 2026

Fixes #2632

Changes to the existing invoke_agent client span:

  • Removed attributes:
    • gen_ai.response.id
    • gen_ai.response.model
  • Added attribute: gen_ai.agent.version
  • server.address requirement level simplified from recommended: when span kind is CLIENT to recommended (since the span is always client kind now)

New invoke_agent internal span (span.gen_ai.invoke_agent.internal):

The internal span is for in-process agents (e.g., LangChain, CrewAI). Compared to the client span, the internal span:

  • Has span_kind: internal (vs client)
  • Does not have server.address or server.port

Comment thread docs/gen-ai/gen-ai-agent-spans.md Outdated
@lmolkova lmolkova moved this from Untriaged to Needs More Approval in Semantic Conventions Triage Mar 9, 2026
@trask trask mentioned this pull request Mar 9, 2026
3 tasks
singankit added a commit to singankit/semantic-conventions that referenced this pull request Mar 10, 2026
Add all attributes from the invoke_agent client span (per PR open-telemetry#3514)
to the server span, including token usage with aggregation notes,
inference request parameters, conversation id, content attributes,
and tool definitions.
@trask trask changed the title Split invoke_agent attributes from inference attribute hierarchy Split invoke_agent into separate client and internal spans, and split attributes from inference hierarchy Mar 10, 2026
trask added 2 commits March 10, 2026 13:41
…from-inference

# Conflicts:
#	docs/gen-ai/gen-ai-agent-spans.md
@singankit
Copy link
Copy Markdown
Contributor

@trask If span kind INTERNAL does not have server.address and server.port, would it enforce to have an HTTP server span to capture these attributes?

Copy link
Copy Markdown

@eternalcuriouslearner eternalcuriouslearner left a comment

Choose a reason for hiding this comment

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

Great stuff!! It's a step in forward direction for providing better transparency in understanding agents. I left few comments to enhance clarity around the documentation. Thanks for this @trask.

Comment thread docs/gen-ai/gen-ai-agent-spans.md
Comment thread docs/gen-ai/gen-ai-agent-spans.md
Comment thread docs/gen-ai/gen-ai-agent-spans.md
@singankit
Copy link
Copy Markdown
Contributor

Does not have token usage attributes (gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.cache_read.input_tokens, gen_ai.usage.cache_creation.input_tokens) — child inference spans provide token data directly

Would this require any inference client being used by agent to have tracing enabled assuming those client libs emit traces? For cases where I use openai client lib to call LLM but I do not have opentelemetry-instrumentation-openai-v2 installed

@Cirilla-zmh
Copy link
Copy Markdown
Member

Would this require any inference client being used by agent to have tracing enabled assuming those client libs emit traces?

I believe so.

This feels more like an implementation limitation than a semantic conventions one. Not every agent invocation exposes token usage in its return value, especially in-process ones. So if the inference client itself isn’t instrumented/traced, instrumentation usually has no cheap way to accurately capture the agent’s token usage.

@singankit
Copy link
Copy Markdown
Contributor

Would this require any inference client being used by agent to have tracing enabled assuming those client libs emit traces?

I believe so.

This feels more like an implementation limitation than a semantic conventions one. Not every agent invocation exposes token usage in its return value, especially in-process ones. So if the inference client itself isn’t instrumented/traced, instrumentation usually has no cheap way to accurately capture the agent’s token usage.

Providing information like token usage (not limited to it) should be responsibility of the agent framework rather than instrumentation lib in my opinion. For example, OpenAI Responses API does it no matter whether it is instrumented or no. Instrumentation libs should definitely capture it.

@Cirilla-zmh
Copy link
Copy Markdown
Member

Cirilla-zmh commented Mar 26, 2026

Providing information like token usage (not limited to it) should be responsibility of the agent framework rather than instrumentation lib in my opinion.

Agree with you. So in any case, we should do our best to count token usage in invoke_agent, unless the framework does not provide a way to do so, right?

Comment thread model/gen-ai/spans.yaml
@trask
Copy link
Copy Markdown
Member Author

trask commented Apr 1, 2026

@trask If span kind INTERNAL does not have server.address and server.port, would it enforce to have an HTTP server span to capture these attributes?

a few options:

  • HTTP (or other protocol) server span
  • "opt-in" to stamping server.* attributes on the span (it is generally acceptable for users to do this, I don't think generic frameworks would know the server.* values anyways)
  • introduce invoke_agent SERVER span (your Invoke agent server span #3473)

@trask
Copy link
Copy Markdown
Member Author

trask commented Apr 1, 2026

Providing information like token usage (not limited to it) should be responsibility of the agent framework rather than instrumentation lib in my opinion.

Agree with you. So in any case, we should do our best to count token usage in invoke_agent, unless the framework does not provide a way to do so, right?

I brought back token usage on internal spans to make this PR easier to move forward (as it was intended to mostly be a mechanical change) and we can discuss that issues separately.

@trask trask moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Apr 3, 2026
@lmolkova lmolkova added this pull request to the merge queue Apr 3, 2026
Merged via the queue into open-telemetry:main with commit bb1dc68 Apr 3, 2026
20 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:gen-ai enhancement New feature or request

Development

Successfully merging this pull request may close these issues.

Remove inference attributes from agent invocation span

7 participants