Split AgentInvocation into LocalAgentInvocation and RemoteAgentInvocation

[lmolkova]

What does this change do?

Splits AgentInvocation into LocalAgentInvocation (SpanKind.INTERNAL) for in-process framework agents and RemoteAgentInvocation (SpanKind.CLIENT) for external agent services, and updates agent instrumentations and conformance scenarios to expect the new metrics.

Why?

Aligns agent spans and metrics with GenAI semantic conventions (agent spans spec):

• Span kind distinction: In-process framework agents use INTERNAL spans, while remote agent calls use CLIENT spans.
• Attributes on local agents:
  • gen_ai.agent.id is removed from local agent spans (only applies to remote agents with service-managed identifiers).
  • Provider and server attributes (gen_ai.provider.name, server.address, server.port) are excluded on local agent spans.
• Attributes on remote agents: Supports gen_ai.agent.id, gen_ai.agent.version, gen_ai.request.previous_response.id, and cache token usage (gen_ai.usage.cache_write.input_tokens, gen_ai.usage.cache_read.input_tokens).
• Duration metric: Records gen_ai.invoke_agent.duration (s) on local agent runs (replacing gen_ai.client.operation.duration), tagged with gen_ai.agent.name and optional gen_ai.request.model.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-04 06:38 UTC

Move out of draft to request review.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

🟡 Changes recommended

The split breaks direct construction of the public base class and omits known remote-agent identity from sampling attributes.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Splits local and remote agent invocation telemetry to align span kinds, attributes, and metrics with GenAI semantic conventions.

Changes:

• Adds dedicated LocalAgentInvocation and RemoteAgentInvocation classes.
• Records local-agent duration metrics while preserving remote client metrics.
• Updates instrumentation tests, conformance expectations, and changelogs.

File summaries

File	Description
util/opentelemetry-util-genai/tests/test_handler_agent.py	Tests split invocation behavior and metrics.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/invocation.py	Exports the new invocation types.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py	Constructs local or remote invocation types.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py	Implements split invocation telemetry.
util/opentelemetry-util-genai/.changelog/616.changed	Documents local duration metrics.
util/opentelemetry-util-genai/.changelog/616.added	Documents new public classes.
instrumentation/opentelemetry-instrumentation-genai-qwen-agent/tests/conformance/invoke_agent.py	Updates expected agent/tool metrics.
instrumentation/opentelemetry-instrumentation-genai-qwen-agent/.changelog/616.changed	Documents metric changes.
instrumentation/opentelemetry-instrumentation-genai-openai-agents/tests/conformance/orchestration.py	Updates orchestration metrics.
instrumentation/opentelemetry-instrumentation-genai-openai-agents/.changelog/616.changed	Documents metric changes.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conformance/agent.py	Updates agent metrics.
instrumentation/opentelemetry-instrumentation-genai-llama-index/.changelog/616.changed	Documents metric changes.
instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_callback_handler.py	Updates local-agent metadata assertions.
instrumentation/opentelemetry-instrumentation-genai-langchain/tests/conformance/agent.py	Adds agent/tool metric expectations.
instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/callback_handler.py	Stops assigning hosted IDs to local agents.
instrumentation/opentelemetry-instrumentation-genai-langchain/.changelog/616.changed	Documents metric and attribute changes.
instrumentation/opentelemetry-instrumentation-genai-agno/tests/conformance/agent.py	Updates agent/tool metrics.
instrumentation/opentelemetry-instrumentation-genai-agno/.changelog/616.changed	Documents metric changes.

Review details

Suppressed comments (1)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py:262

• This link targets the main semantic-conventions repository, where this GenAI document does not live. Point it at open-telemetry/semantic-conventions-genai so the new public class docstring has a working specification reference.

        https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span

• Files reviewed: 18/18 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[DylanRussell]

Recommended Cleanups
google-genai/interactions.py: Change InferenceInvocation | AgentInvocation to InferenceInvocation | RemoteAgentInvocation.
qwen-agent / llama-index / langchain internal handler signatures: Update helper functions like _set_agent_output(invocation: AgentInvocation) to invocation: LocalAgentInvocation where they specifically handle LocalAgentInvocation.

[DylanRussell]

Recommended Cleanups

google-genai/interactions.py: Change InferenceInvocation | AgentInvocation to InferenceInvocation | RemoteAgentInvocation.

qwen-agent / llama-index / langchain internal handler signatures: Update helper functions like _set_agent_output(invocation: AgentInvocation) to invocation: LocalAgentInvocation where they specifically handle LocalAgentInvocation.

[DylanRussell]

nit: we don't need to wrap this in dict() since get_usage_attributes is already creating a new dict

[DylanRussell]

same thing above (and maybe in other places didn't check everything)