Genai utils | Add AgentInvocation type by etserend · Pull Request #4274 · open-telemetry/opentelemetry-python-contrib

etserend · 2026-02-27T17:37:21Z

Description

This PR adds the AgentInvocation type extending _BaseAgent for agent invocation (invoke_agent) spans. It provides TelemetryHandler lifecycle methods and an agent() context manager — aligned with the GenAI agent span semantic conventions.

Builds on the _BaseAgent base class and AgentCreation type added in #4217. Agent metrics and events to come in follow-up PRs.

Type of change

Please delete options that are not relevant.

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Basic unit tests for starting and stopping agent invocation spans
Unit tests for agent invocation with all attributes (request + response)
Unit tests for context manager happy path and error path
Unit tests for AgentInvocation dataclass defaults and messages

Does This PR Require a Core Repo Change?

No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

etserend · 2026-03-02T22:23:33Z

Sample trace from demo app

Trace: ad3749665a3bffcef592d6bacc2a2924

invoke_agent Poetry Agent (1.323s, Client)
├── gen_ai.agent.name: Poetry Agent
├── gen_ai.input.messages: [{"role":"user","parts":[{"content":"What is O...
├── gen_ai.operation.name: invoke_agent
├── gen_ai.output.messages: [{"role":"assistant","parts":[{"content":"Ope...
├── gen_ai.provider.name: openai
├── gen_ai.request.model: gpt-4o-mini
├── gen_ai.response.finish_reasons:
├── gen_ai.response.id: chatcmpl-DHtaXlNpLabc2yKX3TfQ0dlJT5rj9
├── gen_ai.response.model: gpt-4o-mini-2024-07-18
├── gen_ai.usage.input_tokens: 15
├── gen_ai.usage.output_tokens: 36
├── server.address: api.openai.com
├── server.port: 443
│
├── chat gpt-4o-mini (1.323s, Client)
│   ├── gen_ai.input.messages: [{"role":"user","parts":[{"content":"What is O...
│   ├── gen_ai.operation.name: chat
│   ├── gen_ai.output.messages: [{"role":"assistant","parts":[{"content":"Ope...
│   ├── gen_ai.provider.name: openai
│   ├── gen_ai.request.model: gpt-4o-mini
│   ├── gen_ai.response.finish_reasons:
│   ├── gen_ai.response.id: chatcmpl-DHtaXlNpLabc2yKX3TfQ0dlJT5rj9
│   ├── gen_ai.response.model: gpt-4o-mini-2024-07-18
│   ├── gen_ai.usage.input_tokens: 15
│   ├── gen_ai.usage.output_tokens: 36
│   ├── server.address: api.openai.com
│   │
│   └── chat gpt-4o-mini (1.322s, Client)
│       ├── gen_ai.openai.response.service_tier: default
│       ├── gen_ai.operation.name: chat
│       ├── gen_ai.request.model: gpt-4o-mini
│       ├── gen_ai.response.finish_reasons:
│       ├── gen_ai.response.id: chatcmpl-DHtaXlNpLabc2yKX3TfQ0dlJT5rj9
│       ├── gen_ai.response.model: gpt-4o-mini-2024-07-18
│       ├── gen_ai.system: openai
│       ├── gen_ai.usage.input_tokens: 15
│       ├── gen_ai.usage.output_tokens: 36
│       └── server.address: api.openai.com

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

eternalcuriouslearner

Overall LGTM!! I left few questions to understand:

If we need to improve overall robustness of error handling.
early capture of few sem conv.

I used this doc for reviewing if sem conv are captured correctly or not. Additionally does it make sense to make this pr specific for agent invocation and removing agent creation specific code.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

wrisa

LGTM. Though would need refactoring in handler.py in case other PRs are merged first.

eternalcuriouslearner

question: Do we have GEN_AI_AGENT_VERSION, GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS, GEN_AI_TOOL_DEFINITIONS and GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS in opentelemetry.semconv._incubating.attributes?

etserend · 2026-03-11T18:05:06Z

question: Do we have GEN_AI_AGENT_VERSION, GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS, GEN_AI_TOOL_DEFINITIONS and GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS in opentelemetry.semconv._incubating.attributes?

Yes @eternalcuriouslearner , all four constants in semconv package and referenced them via the GenAI. alias.

etserend · 2026-03-17T20:39:04Z

Verified the AgentInvocation type and TelemetryHandler.agent() context manager end-to-end using the Vertex AI SDK with VertexAIInstrumentor auto-instrumentation.

Demo PR: #4340

Steps exercised:

invoke_agent span wrapping a generate_content LLM call
Auto-instrumented chat span appears as child of invoke_agent (same trace)
Token usage populated from response metadata

Trace (60e99da09ed18470d275be708544362d)
└── invoke_agent Currency Exchange Agent (6.70s, Client)
    ├── gen_ai.operation.name: invoke_agent
    ├── gen_ai.agent.name: Currency Exchange Agent
    ├── gen_ai.agent.description: Currency exchange agent demo
    ├── gen_ai.provider.name: gcp_vertex_ai
    ├── gen_ai.request.model: gemini-2.5-flash
    ├── gen_ai.response.finish_reasons: ["stop"]
    ├── gen_ai.usage.input_tokens: 12
    ├── gen_ai.usage.output_tokens: 163
    ├── gen_ai.input.messages: [{"role":"user","parts":[{"content":"What is the..."}]}]
    ├── gen_ai.output.messages: [{"role":"assistant","parts":[{"content":"As of..."}]}]
    ├── server.address: us-central1-aiplatform.googleapis.com
    │
    └── chat gemini-2.5-flash (6.67s, Client)
        ├── gen_ai.operation.name: chat
        ├── gen_ai.request.model: gemini-2.5-flash
        ├── gen_ai.response.model: gemini-2.5-flash
        ├── gen_ai.response.finish_reasons: ["stop"]
        ├── gen_ai.usage.input_tokens: 12
        ├── gen_ai.usage.output_tokens: 163
        ├── gen_ai.input.messages: [{"role":"user","parts":[{"content":"What is the..."}]}]
        ├── gen_ai.output.messages: [{"role":"model","parts":[{"content":"As of..."}]}]
        ├── server.address: us-central1-aiplatform.googleapis.com
        └── server.port: 443

keith-decker · 2026-03-19T16:21:49Z

@etserend Note: based on the discussion in SIG today, we should not be introducing new start_, stop_ and fail_* methods.

see #4219 for the discussion and examples.

pradystar · 2026-03-27T16:35:05Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

+        (GenAI.GEN_AI_USAGE_INPUT_TOKENS, invocation.input_tokens),
+        (GenAI.GEN_AI_USAGE_OUTPUT_TOKENS, invocation.output_tokens),
+        (
+            "gen_ai.usage.cache_creation_input_tokens",


wrong name, should be gen_ai.usage.cache_creation.input_tokens. Also if this is not available in the current version of semconv attributes maybe extra to constant?

pradystar · 2026-03-27T16:35:36Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

+            invocation.cache_creation_input_tokens,
+        ),
+        (
+            "gen_ai.usage.cache_read_input_tokens",


wrong name, should be gen_ai.usage.cache_read.input_tokens. Also if this is not available in the current version of semconv attributes maybe extra to constant?

pradystar · 2026-03-27T16:36:16Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

    return _get_span_name(invocation)


+def _get_system_instructions_for_span(


not used anywhere, is this needed?

pradystar · 2026-03-27T16:38:09Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

        self.stop(invocation)

+    # Agent-specific convenience methods
+    def start_agent(self, invocation: AgentInvocation) -> AgentInvocation:


do we still need these methods if we are handling all invocation types in start, stop and fail methods?

pradystar · 2026-03-27T16:44:19Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py


    def _start(self, invocation: _T) -> _T:
        """Start a GenAI invocation and create a pending span entry."""
+        kind = SpanKind.CLIENT


should we add a span_kind field on AgentInvocation or base GenAIInvocation defaulting to SpanKind.CLIENT so that this can be supported?

github-actions bot assigned DylanRussell Feb 27, 2026

etserend force-pushed the genai-utils/agent-invocation branch from 1b5cd9f to 08e2b07 Compare February 27, 2026 17:45

github-actions bot assigned lmolkova Feb 27, 2026

etserend changed the title ~~Genai utils/agent invocation~~ Genai utils/Add AgentInvocation type Mar 2, 2026

etserend changed the title ~~Genai utils/Add AgentInvocation type~~ Genai utils | Add AgentInvocation type Mar 2, 2026

etserend marked this pull request as ready for review March 2, 2026 22:23

etserend requested a review from a team as a code owner March 2, 2026 22:23

tammy-baylis-swi added this to Python PR digest Mar 3, 2026

tammy-baylis-swi moved this to Ready for review in Python PR digest Mar 3, 2026

keith-decker reviewed Mar 3, 2026

View reviewed changes

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Show resolved Hide resolved

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py Outdated Show resolved Hide resolved

github-actions bot assigned keith-decker Mar 6, 2026

etserend force-pushed the genai-utils/agent-invocation branch from e0ee125 to 25411ca Compare March 6, 2026 16:28

eternalcuriouslearner reviewed Mar 8, 2026

View reviewed changes

wrisa reviewed Mar 9, 2026

View reviewed changes

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated Show resolved Hide resolved

wrisa approved these changes Mar 10, 2026

View reviewed changes

eternalcuriouslearner approved these changes Mar 10, 2026

View reviewed changes

keith-decker approved these changes Mar 19, 2026

View reviewed changes

keith-decker self-requested a review March 19, 2026 16:23

etserend added 6 commits March 26, 2026 14:39

GenAI Utils | Agent Base Type and Creation Span

843124d

fix lint and add _BaseAgent to sphinx nitpick exceptions

da8232d

align AgentInvocation with invoke_agent semconv

f849547

update span utils

c6e9822

apply _lifecycle_context and error handling

d28860a

apply general invoke methods and resolved merge conflict

c320ca6

etserend force-pushed the genai-utils/agent-invocation branch from a3a0f9e to c320ca6 Compare March 26, 2026 21:41

pradystar reviewed Mar 27, 2026

View reviewed changes

		return _get_span_name(invocation)


		def _get_system_instructions_for_span(

Conversation

etserend commented Feb 27, 2026

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eternalcuriouslearner left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wrisa left a comment

Choose a reason for hiding this comment

Uh oh!

eternalcuriouslearner left a comment

Choose a reason for hiding this comment

Uh oh!

etserend commented Mar 11, 2026

Uh oh!

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

Uh oh!

Uh oh!

keith-decker commented Mar 19, 2026

Uh oh!

pradystar Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

pradystar Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

pradystar Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

pradystar Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

pradystar Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

etserend commented Mar 2, 2026 •

edited

Loading

eternalcuriouslearner left a comment •

edited

Loading

etserend commented Mar 17, 2026 •

edited

Loading