docs(gen-ai): clarify remote client vs local internal agent invocations (#493) - #524
1aifanatic wants to merge 3 commits into
Conversation
…-telemetry#493) Clarify the architectural distinction between remote/hosted agent services (gen_ai.invoke_agent.client with CLIENT kind) and local in-process agent execution (gen_ai.invoke_agent.internal with INTERNAL kind). Document span expectations in distributed multi-tier architectures where a remote client calls an agent service that executes an agent internally.
Pull request dashboard statusWaiting on reviewers · refreshed 2026-09-18 03:08 UTC Review the latest changes. Status above doesn't look right?
|
There was a problem hiding this comment.
🟡 Changes recommended
The guidance excludes non-network process boundaries and lacks a distributed reference scenario.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Clarifies how GenAI agent spans represent remote and in-process execution.
Changes:
- Distinguishes
CLIENTandINTERNALagent invocations. - Documents distributed trace structure and context propagation.
- Adds a clarification changelog entry.
File summaries
| File | Description |
|---|---|
model/gen-ai/spans.yaml |
Refines agent span guidance. |
docs/gen-ai/gen-ai-agent-spans.md |
Documents local, remote, and distributed execution. |
changelog.d/524.clarification.md |
Records the clarification. |
Review details
Suppressed comments (3)
model/gen-ai/spans.yaml:571
- This leaves out agent services running in another process over non-network IPC. Those invocations are not eligible for an
INTERNALspan, so the fallback should use the same process-boundary test as the span's brief.
For agent invocations across a network boundary to a remote service,
instrumentations SHOULD use `gen_ai.invoke_agent.client` instead.
docs/gen-ai/gen-ai-agent-spans.md:44
- This makes both W3C fields appear mandatory for every transport, but OpenTelemetry propagators are configurable and
tracestateis optional even with W3C Trace Context. Also, gRPC exposes carrier entries as metadata rather than headers. Describe propagation through the configured propagator and keep W3C as an example.
2. Trace context (W3C `traceparent` and `tracestate`) is propagated over the transport protocol (e.g. HTTP or gRPC headers).
docs/gen-ai/gen-ai-agent-spans.md:48
- This establishes a new expectation that client and internal agent spans coexist in one propagated distributed trace, but no reference scenario demonstrates that relationship. Existing scenarios emit either
gen_ai.invoke_agent.clientorgen_ai.invoke_agent.internalindependently, and the citedopenai-agentsrun covers only the local span. Add a library-backed distributed scenario that records both spans and their propagated parentage.
Both the `CLIENT` and `INTERNAL` spans are expected and valid in distributed traces: the client span measures end-to-end caller-perceived duration and transport errors, while the internal span captures server-side execution details, reasoning cycles, and child operations.
- Files reviewed: 3/3 changed files
- Comments generated: 2
- Review effort level: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| GenAI agent execution models fall into two primary categories: | ||
|
|
||
| - **Remote (hosted) agents (`CLIENT` kind)**: | ||
| An application or orchestrator invokes an external, hosted agent service across a network boundary (e.g. over HTTP or gRPC). Examples include cloud-managed agent platforms (OpenAI Assistants API, AWS Bedrock Agents, Google Cloud Vertex AI Reasoning Engine, Azure AI Foundry Agent Service) or custom enterprise agent microservices. These invocations are instrumented using `gen_ai.invoke_agent.client` with span kind `CLIENT`, capturing caller-observed latency, transport errors, and high-level request parameters. |
There was a problem hiding this comment.
Addressed in 589c958: generalized the definition to out-of-process boundaries (covering both network transports and local IPC), and clarified context propagation through configured propagators (such as W3C Trace Context over HTTP headers, gRPC metadata, or IPC context).
| A client span describes invoking a remote or hosted agent service across a | ||
| network boundary (e.g. OpenAI Assistants API, AWS Bedrock Agents, Google Cloud | ||
| Vertex AI Reasoning Engine, Azure AI Foundry Agent Service, or a remote agent microservice). |
There was a problem hiding this comment.
Addressed in 589c958: updated to describe out-of-process agent services across process boundaries (including local IPC) rather than solely network boundaries.
|
/dashboard route:reviewers |
|
@1aifanatic, this pull request was routed to reviewers. The handoff remains active across pushes until newer actionable human feedback arrives. Top-level feedback through this request will not return; unresolved review threads remain open. |
Description
Fixes #493.
This PR clarifies the architectural distinction between remote (hosted) agent services and local (in-process) agent executions in the GenAI semantic conventions:
Local vs Remote Execution Models:
gen_ai.invoke_agent.client(CLIENTkind): Represents invoking a remote or hosted agent service across a network boundary (e.g., OpenAI Assistants API, AWS Bedrock Agents, Google Cloud Vertex AI Reasoning Engine, Azure AI Foundry Agent Service, or custom enterprise agent microservices).gen_ai.invoke_agent.internal(INTERNALkind): Represents an agent framework executing the reasoning and orchestration loop locally within the calling process (e.g., LangChain, CrewAI, AutoGen, Google ADK).Distributed and Multi-Tier Agent Architectures:
CLIENTandINTERNALspans are expected and valid in distributed traces (addressing questions from [gen-ai] Clarify invoke_agent span creation responsibility in distributed scenarios #308): the client span measures caller-observed network duration and errors, while the internal span captures server-side execution details, reasoning cycles, tool invocations, and child operations.Updated Model Notes:
briefandnoteinmodel/gen-ai/spans.yamlfor both span types and regenerated docs using Weaver.changelog.d/524.clarification.md.Verification
weaver registry check: passed with zero policy violations.weaver registry update-markdown: successfully updated embedded snippets in documentation.towncrier build --draft: verified changelog rendering.run-scenario openai-agents: passed.