Invoke agent server span by singankit · Pull Request #3473 · open-telemetry/semantic-conventions

singankit · 2026-02-24T07:11:55Z

Changes

Add invoke agent span for server as counterpart to existing client invoke agent span. This helps capture server perspective of agent invocation.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

Add support for OpenAI Responses API operation type in the gen_ai.operation.name attribute.

…t enum - Rename gen_ai.api.type to openai.api.type (OpenAI-specific attribute) - Remove 'version' from brief description - Change from free-form string to strict enum (chat_completions, responses) - Remove stale 'responses' operation value from gen_ai.operation.name docs - Update OpenAI registry docs with new attribute

…nd inherited opt_in attrs

trask · 2026-02-26T00:58:18Z

+      This span is the server counterpart of the [invoke agent client span](/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span).
+      It's reported by the GenAI agent server when it receives and processes
+      an agent invocation request from a client.
+    extends: attributes.gen_ai.inference.client


we may want to extract a common attribute group for client/server

at the same time, I'm a bit unsure if the existing invoke_agent client span is correct in extending the inference client attributes, and so unsure if we should create .inference.common or .invoke_agent.common

cc @lmolkova

unsure if the existing invoke_agent client span is correct in extending the inference client attributes

yep, it's not right and we should fix it - #2632

we may want to extract a common attribute group for client/server

👍

Splitting invoke_agent from inference in: #3514

I'll follow-up after this PR to split out "common" invoke_agent for client/server.

I think we can make progress here right now - we should not extend client invoke_agent here anyway

@lmolkova Is the suggestion to update this PR after @trask PR #3514 gets merged? Or can we move forward with merging this PR and update once other PR goes in?

I think @lmolkova's suggesting to go ahead and extend attributes.gen_ai.common.client here. That way you don't need to inherit the few inferences attributes we are removing from invoke_agent in #3514, and then we can follow-up later (after both PRs land) with adding attributes.gen_ai.invoke_agent.common, at which point it should be a pure yaml refactoring (and shouldn't affect any markdown files).

Resolved in 042fecf and 048bde5

lmolkova · 2026-02-27T20:08:18Z

+      - ref: client.address
+        requirement_level:
+          recommended: If applicable
+      - ref: client.port
+        requirement_level:
+          recommended: When `client.address` is set.


it this actually helpful on GenAI spans? If users want HTTP/transport details, they should enable corresponding spans. I can see it could become useful, but do we need it right now?

perhaps opt-in, in case HTTP is not instrumented.

it's important for security, but it still privacy concern

Make client.address and client.port as opt-in

Resolved in this commit 4f71b3a

lmolkova · 2026-03-09T19:37:06Z

+
+      **Span kind** MUST be `SERVER`.
+
+      This span is the server counterpart of the [invoke agent client span](/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span).


what does this mean? does it explain anything to server instrumentation authors or consumers of telemetry?

Thanks have update the description and updated it to It represents processing of agent invocation requested by a client.

lmolkova · 2026-03-09T19:40:04Z

+      It's reported by the GenAI agent server when it receives and processes
+      an agent invocation request from a client.


maybe

Suggested change

It's reported by the GenAI agent server when it receives and processes

an agent invocation request from a client.

It represents processing of agent invocation requested by a client.

?

I think 'receives' is covered by protocol spans and depends on how the request is received. This one represents something that happens after receive - processing

lmolkova · 2026-03-09T19:40:57Z

+      This span is the server counterpart of the [invoke agent client span](/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span).
+      It's reported by the GenAI agent server when it receives and processes
+      an agent invocation request from a client.
+    extends: attributes.gen_ai.inference.client


I think we can make progress here right now - we should not extend client invoke_agent here anyway

Replace 'server counterpart' reference with a concise description of what the span represents, consistent with how other server spans (MCP, HTTP, RPC) describe themselves in the codebase.

Per review feedback, the server span should not inherit inference-specific attributes. Extend attributes.gen_ai.common.client instead.

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.

github-actions · 2026-04-01T04:17:39Z

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

wolfgangcodes · 2026-05-05T18:49:31Z

Hello @singankit!

With the merging of Move GenAI semantic conventions to its own dedicated repository, the area:gen-ai semantic conventions have a new home. We've made this split in an to be better able to support the rapid pace of change that we are seeing with Gen AI related semantic conventions.

Our ask is that you move this PR to the new repo here: https://github.com/open-telemetry/semantic-conventions-genai

The contribution guide for the new repo can be found here: https://github.com/open-telemetry/semantic-conventions-genai/blob/main/CONTRIBUTING.md. A major difference is making sure there's a representative scenario and reference outlined in:

4. Update reference scenarioss
Changes under model/ or docs/ typically require updating the reference scenarios under reference/ to demonstrate that the proposed updates are capturable.

You may also find that you need to additional updates to you proposal as the new repo use the V2 Schema.

If you would like to discuss or have questions you can reply here, post in slack here, or add an agenda item for the Gen AI SIG.

Thank you so much!

singankit requested review from a team as code owners February 24, 2026 07:11

github-project-automation Bot added this to Semantic Conventions Triage Feb 24, 2026

github-project-automation Bot moved this to Untriaged in Semantic Conventions Triage Feb 24, 2026

github-actions Bot added enhancement New feature or request area:openai labels Feb 24, 2026

singankit added 6 commits February 23, 2026 23:14

Add responses operation value to gen_ai.operation.name

01d5d39

Add support for OpenAI Responses API operation type in the gen_ai.operation.name attribute.

Docs generation

1b00021

Addressing Feedback

7915c7e

chore: retrigger CI

9eceebc

Invoke Agent Server Span

0d83b95

singankit force-pushed the users/singankit/invoke_agent_server_span branch from 1f6695c to 0d83b95 Compare February 24, 2026 07:20

singankit added 2 commits February 23, 2026 23:22

Remove .chloggen/gen-ai-api-type.yaml

9d5c61a

Add changelog entry for invoke_agent server span

528a52b

github-actions Bot added the area:gen-ai label Feb 25, 2026

singankit changed the title ~~Users/singankit/invoke agent server span~~ Invoke agent server span Feb 25, 2026

Reference issue open-telemetry#3334 in changelog

b6910a0

trask reviewed Feb 25, 2026

View reviewed changes

Comment thread model/gen-ai/spans.yaml Outdated

Comment thread model/gen-ai/spans.yaml Outdated

Comment thread model/gen-ai/spans.yaml

Comment thread model/gen-ai/spans.yaml

Address review feedback: add agent.version, remove redundant briefs a…

4bfe5b3

…nd inherited opt_in attrs

trask reviewed Feb 26, 2026

View reviewed changes

Fix server.address requirement_level formatting

1eac5a3

lmolkova reviewed Feb 27, 2026

View reviewed changes

lmolkova moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Mar 2, 2026

singankit mentioned this pull request Mar 4, 2026

REQUEST: New membership for singankit open-telemetry/community#3307

Closed

6 tasks

singankit added 2 commits March 6, 2026 15:02

Make client.address and client.port opt-in for invoke agent server span

4f71b3a

Regenerate docs for client.address and client.port opt-in change

e0380be

trask approved these changes Mar 9, 2026

View reviewed changes

lmolkova reviewed Mar 9, 2026

View reviewed changes

singankit added 5 commits March 9, 2026 16:20

Improve invoke_agent server span note to be self-descriptive

b0472f6

Replace 'server counterpart' reference with a concise description of what the span represents, consistent with how other server spans (MCP, HTTP, RPC) describe themselves in the codebase.

Merge upstream/main and resolve doc conflicts

10368c5

Regenerate docs with weaver

7aaf44f

Extend common.client instead of inference.client for server span

042fecf

Per review feedback, the server span should not inherit inference-specific attributes. Extend attributes.gen_ai.common.client instead.

Add all invoke_agent attributes to server span

048bde5

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.

lmolkova approved these changes Mar 17, 2026

View reviewed changes

lmolkova moved this from Awaiting codeowners approval to Ready to be Merged in Semantic Conventions Triage Mar 17, 2026

github-actions Bot added the Stale label Apr 1, 2026

trask mentioned this pull request Apr 1, 2026

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

Merged

lmolkova moved this from Ready to be Merged to Blocked in Semantic Conventions Triage Apr 2, 2026

github-actions Bot closed this Apr 9, 2026

lmolkova reopened this Apr 28, 2026

github-actions Bot removed the Stale label Apr 29, 2026


		Span kind MUST be `SERVER`.

		This span is the server counterpart of the [invoke agent client span](/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span).

		It's reported by the GenAI agent server when it receives and processes
		an agent invocation request from a client.

	It's reported by the GenAI agent server when it receives and processes
	an agent invocation request from a client.
	It represents processing of agent invocation requested by a client.

Conversation

singankit commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Merge requirement checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmolkova Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmolkova Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

wolfgangcodes commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

singankit commented Feb 24, 2026 •

edited

Loading

lmolkova Mar 3, 2026 •

edited

Loading

lmolkova Mar 9, 2026 •

edited

Loading