[bot] Instrument A2A SDK (2,761,407 weekly downloads)

[braintrust-bot]

Summary

a2a-sdk is the official Python SDK for the Agent2Agent (A2A) protocol, maintained by the a2aproject org (backed by Google and a Linux Foundation technical steering committee with AWS, Cisco, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow participating). A2A reached a stable v1.0 spec in April 2026 and has production integrations in Azure AI Foundry, Copilot Studio, and Amazon Bedrock AgentCore Runtime. It defines an agent-to-agent execution surface distinct from MCP's tool-calling model: a client sends a task/message to a remote agent (message/send / message/stream JSON-RPC methods, exposed client-side via the a2a.client module) which triggers that agent's own reasoning/tool-use and returns a Task/Message result, with streaming (SSE) and polling (tasks/get, tasks/cancel) variants. Server-side, an agent implements this execution surface via AgentExecutor.execute(context, event_queue).

This repository has zero instrumentation for it — no py/src/braintrust/integrations/a2a* directory, no wrapper, no nox session, no cassette directory, and no entry in py/pyproject.toml's [tool.braintrust.matrix].

This is comparable in scope to other agent-run execution surfaces this repo already instruments (e.g. the tool-calling execution surface covered by the standalone MCP Python SDK gap already filed in #567), but for cross-agent delegation rather than local tool invocation.

Weekly downloads

Weekly downloads: 2,761,407 (as of 2026-07-23; https://pypistats.org/packages/a2a-sdk). Cross-checked against https://pepy.tech/projects/a2a-sdk, which shows 11,263,287 downloads over the trailing 30 days (~2.6M/week), consistent with the pypistats figure.

Braintrust docs status

not_found. Checked https://www.braintrust.dev/docs/guides/tracing and https://www.braintrust.dev/docs/guides/tracing/integrations — neither the provider list ("OpenAI, Anthropic, Gemini, AWS Bedrock, Azure, Mistral, Together, Groq, and many more") nor the agent-framework list ("OpenAI Agents SDK, Claude Agent SDK, Pi Coding Agent SDK, Deep Agents, LangGraph, CrewAI, AutoGen, AgentScope, Google ADK, LiveKit Agents, Mastra, Pydantic AI, Strands Agents SDK") mentions A2A or Agent2Agent.

What needs to be instrumented

• Client-side: a2a.client message-send/stream execution (JSON-RPC message/send, message/stream) — the primary "call a remote agent" entrypoint, analogous to an agent-run span.
• tasks/get / tasks/cancel polling for long-running task status.
• Server-side: AgentExecutor.execute(context, event_queue) — the entrypoint an A2A-compliant agent implements to handle an incoming task; wrapping this would capture the receiving agent's execution as a span.

Upstream sources

• PyPI: https://pypi.org/project/a2a-sdk/
• GitHub (official): https://github.com/a2aproject/a2a-python
• API reference: https://a2a-protocol.org/latest/sdk/python/api/
• Protocol spec / governance: https://a2a-protocol.org

Local repo files inspected

• py/src/braintrust/integrations/ — no a2a directory
• py/src/braintrust/wrappers/ — no A2A wrapper
• py/pyproject.toml [tool.braintrust.matrix] — no a2a-sdk entry
• py/noxfile.py — no test_a2a session
• Repo-wide case-insensitive grep for a2a[-_]sdk under py/ — zero matches

[AbhiPrasad]

Spec compliance review

Automated review of the requirements stated in this issue against the Braintrust instrumentation specification (braintrust-spec → skills/instrumentation-spec/references/instrumentation-guide.md and references/features/). This reviews the issue text, not any implementation.

Verdict: UNDERSPECIFIED
Category: other — cross-process agent-to-agent RPC transport. Not a completion API and not an agentic framework in the spec's sense; there is no model provider anywhere in the surface. The server-side AgentExecutor.execute entrypoint is the only agentic-shaped piece.
Already implemented in this repo: no. There is no py/src/braintrust/integrations/a2a* directory, no wrapper under py/src/braintrust/wrappers/, no test_a2a session in py/noxfile.py, and no a2a-sdk key in py/pyproject.toml [tool.braintrust.matrix]. The issue's "zero instrumentation" claim is accurate — a repo-wide grep for a2a returns only base64 noise inside unrelated cassettes (e.g. py/src/braintrust/integrations/langchain/cassettes/latest/test_llm_calls.yaml), not source references.

This issue is a library-gap stub. It identifies what library to instrument and which entrypoints exist, but states no instrumentation requirements: no span types, no span names, no input/output shapes, no metadata, no metrics, no trace propagation, no streaming semantics, no error handling, and no context.span_origin provenance. Because A2A is a cross-process protocol, the omitted propagation contract is the single highest-risk gap — an A2A integration that does not implement it produces two disconnected traces per agent hop and is strictly worse than no integration at all.

Consequently, most findings below are missing requirements rather than conflicts.

---

Conflicts with the spec

1. The client-side call is described as an agent-run span. It is not.

Client-side: a2a.client message-send/stream execution (JSON-RPC message/send, message/stream) — the primary "call a remote agent" entrypoint, analogous to an agent-run span.

Per instrumentation-guide § Completion APIs vs Agentic APIs and § Agentic API Instrumentation, the agentic span tree (task parent + child llm/tool spans) is emitted by the component that runs the tool-use loop. The A2A client runs no loop — it issues one JSON-RPC request. The loop runs in the remote process, behind AgentExecutor.execute. Describing the client span as "an agent-run span" invites an implementation that emits a task parent representing the remote agent's run, which duplicates the remote agent's own task span whenever both ends are instrumented, and fabricates a parent for children it never observed.

Correction: the client emits a single delegation span with no synthesized children. The remote agent's real span tree attaches to it across the process boundary via W3C propagation (features/distributed-tracing.md § Send behavior / § Receive behavior), not by client-side reconstruction. Add an explicit non-goal: the client MUST NOT synthesize child llm or tool spans for work executed in another process.

2. A2A is framed against the provider list, implying provider-like span shaping.

Checked https://www.braintrust.dev/docs/guides/tracing and https://www.braintrust.dev/docs/guides/tracing/integrations — neither the provider list … nor the agent-framework list … mentions A2A or Agent2Agent.

A2A carries no model identifier, no token usage, and no pricing surface. Per instrumentation-guide § Metadata and features/token-and-cost-metrics.md § Span identity, every llm span MUST carry both metadata.model and metadata.provider; A2A can supply neither, for either the client or the server side. An A2A integration therefore emits zero llm spans.

This has a load-bearing downstream consequence the issue should state explicitly: the § Canonical payload format requirement ("instrumentation MUST convert payloads into the OpenAI Chat Completions format") is scoped to LLM input/output. It does not apply to A2A Message/Part/Task protocol envelopes, and an implementation MUST NOT contort A2A envelopes into a fake messages array to satisfy it. What does go in input/output still needs defining — see Missing requirements #4.

3. tasks/get / tasks/cancel are listed as instrumentation targets.

tasks/get / tasks/cancel polling for long-running task status.

These are pure control-plane RPCs with no AI content. Instrumenting them as spans conflicts with instrumentation-guide § Data capturing policy — "Instrumentation MUST NOT capture any data or fields unless this guide explicitly requires or allows them", whose stated rationale is data volume and PII. A polling loop emits one span per poll, which is unbounded span volume for zero observability value.

It is also self-defeating under features/filter-ai-spans.md § Filtering decision: such spans carry no attribute with a gen_ai., braintrust., llm., ai., or traceloop. prefix, so in any OTel-based deployment with BRAINTRUST_FILTER_AI_SPANS=true they are silently discarded anyway. Net effect is noise in native deployments and invisibility in OTel ones.

Correction: do not emit standalone spans for tasks/get / tasks/cancel. Fold the terminal task state into the originating client delegation span's output (or error, per Missing requirements #8).

4. The server-side entrypoint is described as producing "a span", untyped and unparented.

Server-side: AgentExecutor.execute(context, event_queue) — the entrypoint an A2A-compliant agent implements to handle an incoming task; wrapping this would capture the receiving agent's execution as a span.

Two spec requirements are elided by the singular "a span":

• Per instrumentation-guide § Agentic API Instrumentation → Parent span (the agent run), this span MUST have span_attributes.type = "task" and a descriptive span_attributes.name. It is a parent, not a leaf — the agent's internal model calls and tool executions are child llm and tool spans, contributed by whatever provider integration is active inside the executor.
• Per features/distributed-tracing.md § Receive behavior item 1, this span MUST NOT be a root span when valid inbound trace context is present. It MUST share the inbound trace id and be parented to the inbound span. As written, the requirement reads as "start a span", which is exactly the non-conforming implementation.

---

Missing requirements

1. Cross-process trace propagation — the entire features/distributed-tracing.md contract is absent.

This is the highest-risk omission and the whole reason A2A is worth instrumenting. Required:

• Send (client). Per § Send behavior, inject lowercase traceparent (and tracestate when present) from the current span's context, plus baggage containing braintrust.parent=<project_id:...|project_name:...|experiment_id:...>, into the outbound JSON-RPC HTTP request headers.
• Receive (server). Per § Receive behavior, resolve a parent from the inbound carrier using case-insensitive header lookup, and start the AgentExecutor.execute task span under it. If traceparent is valid but no braintrust.parent baggage entry is present, still adopt the incoming trace identity and route under the currently-active logger/experiment. If no valid traceparent is present (e.g. a third-party non-Braintrust A2A client), start a fresh root span.

The Python SDK already ships every primitive needed, so this is wiring, not new machinery:

• py/src/braintrust/propagation.py — W3C traceparent/baggage parse/format, BRAINTRUST_PARENT_KEY, merge_baggage, get_header, PropagatedState for tracestate/trace_flags pass-through
• py/src/braintrust/logger.py:2483 — inject_trace_context(carrier, span)
• py/src/braintrust/logger.py:2504 — extract_trace_context(headers) → opaque context for start_span(parent=...)
• py/src/braintrust/logger.py:262, py/src/braintrust/logger.py:388, py/src/braintrust/logger.py:4686 — Span.inject(carrier)

Existing conformance coverage to mirror lives in py/src/braintrust/test_propagation.py.

2. Propagation conformance details, all omitted.

From features/distributed-tracing.md § Test cases:

• Preserve non-Braintrust baggage members byte-for-byte on relay; only braintrust.parent is SDK-owned (§ Wire format → baggage and braintrust.parent).
• Percent-encode the braintrust.parent value per the W3C baggage-octet grammar; encode/decode MUST be inverses (a literal + survives as +; space is %20) (§ Send: braintrust.parent value encoding).
• Injected header names MUST be lowercase; a pre-existing case-variant (Baggage, Traceparent) MUST be overwritten in place, not duplicated (§ Send behavior).
• Bound relayed baggage to both 64 list-members and 8192 bytes, dropping whole members only, with braintrust.parent reserving its slot and byte cost first (§ Baggage size limits).
• Forward inbound tracestate unchanged on any later inject within the trace; emit none when none was inbound (§ Round trip).
• inject is a no-op under legacy UUID ids — no traceparent, no baggage, pre-existing carrier entries untouched (§ Native SDK ID format and back-compat).
• Malformed traceparent (bad version, wrong length, zero ids) → treated as absent → fresh root.
• Propagation is best-effort: injecting MUST NOT fail or drop the span if the Braintrust parent is unknown, and an oversized/invalid inbound baggage MUST NOT throw (§ Negative / robustness).

3. Span types and names are not specified for any of the three named surfaces.

The issue names entrypoints but proposes no span_attributes.type or span_attributes.name for any of them. See instrumentation-guide § Span types and § Span naming. (Note the client-side type is genuinely undecided at the spec level — see Blocked on spec changes #1.)

4. input / output payload shape is not specified.

A2A Message, Part, and Task are protocol envelopes, not chat completions. The issue must define concretely:

• Client delegation span input: the outbound Message and its parts.
• Client delegation span output: the terminal Task (including its final status) or Message result.
• Server task span input/output: the inbound request message and the final produced result.

And, per instrumentation-guide § Multimodal / Attachments: A2A FilePart values carrying inline bytes MUST be replaced in place with braintrust_attachment reference objects ({"type": "braintrust_attachment", "content_type": ..., "filename": ..., "key": <uuid v4>}). Raw media bytes MUST NOT remain inline in input/output, and instrumentation MUST NOT emit a separate attachments field or metadata.attachments. A FilePart carrying a remote uri SHOULD be logged as a URL — instrumentation MUST NOT fetch arbitrary remote URLs to create an attachment.

5. Metadata allowlist is not addressed.

instrumentation-guide § Data capturing policy is a closed allowlist: "New captured fields MUST be added to this specification before SDKs emit them." § Metadata closes it explicitly: "Any additional metadata field requires a specification update before SDKs emit it."

The sanctioned metadata keys today are model, provider, temperature, top_p, max_tokens, frequency_penalty, presence_penalty, stop, response_format, tools, tool_choice, parallel_tool_calls, max_tool_calls, prompt (§ Prompt metadata), and tool_approval on tool spans (features/tool-approval-metadata.md).

None of the obvious A2A fields is sanctioned: agent_card, agent_url, agent_name, task_id, context_id, skill, skill_id, task_state, message_id, reference_task_ids. An implementation that emits any of them is non-conforming today. This needs a spec extension filed first — see Blocked on spec changes #2.

6. Metrics are not addressed.

instrumentation-guide § Metrics Reference: "SDKs MUST NOT add metrics beyond the keys listed in this guide. Add new metric keys to this specification before emitting them."

For A2A spans that means start and end only. Concretely: no a2a_* keys, no task_duration, no poll_count, no retry_count, no artifact_count. And since A2A reports no token usage, token metrics MUST be omitted, not zero-filled — features/token-and-cost-metrics.md § Canonical metrics: "Omit a metric when the provider did not report it and the SDK cannot compute it accurately. Do not fabricate zero values to hide missing provider data."

7. Streaming is not specified.

message/stream is SSE. Per instrumentation-guide § Streaming → Accumulation, the SDK MUST accumulate streamed events and produce a single span with complete input and output, structurally identical to the non-streaming message/send case. It MUST NOT emit one span per TaskStatusUpdateEvent / TaskArtifactUpdateEvent, and the user MUST NOT have to do anything different to get complete logged data for the streamed path.

8. Error handling is not specified.

Per instrumentation-guide § Span Data Model, failures belong in the top-level error field. features/tool-approval-metadata.md restates this: "Failed tool calls are represented by a non-null top-level error value." So:

• JSON-RPC error responses MUST set error.
• Terminal TaskState.failed, TaskState.rejected, and TaskState.canceled MUST set error on the corresponding span rather than being encoded only as a metadata flag or a normal output.
• Transport-level failures (connection refused, timeout on a long-running task) MUST set error and MUST NOT prevent span export.

9. context.span_origin provenance is not specified.

instrumentation-guide § Context: "Braintrust-created spans MUST also include span-origin provenance." The repo convention is to pass internal={"instrumentation": "a2a-auto"} to start_span, which is stamped into context.span_origin.instrumentation.name. See the SpanInternalOptions definition at py/src/braintrust/logger.py:150-161, and prior art _INSTRUMENTATION = "strands-auto" at py/src/braintrust/integrations/strands/tracing.py:13 and _INSTRUMENTATION = "adk-auto" at py/src/braintrust/integrations/adk/tracing.py:22.

10. Repo mechanics are listed as missing but never proposed.

The issue's "Local repo files inspected" section correctly enumerates what does not exist, but sets no acceptance criteria. An implementable issue needs:

• [tool.braintrust.matrix] pins in py/pyproject.toml for a2a-sdk — a latest key pinned to an explicit version plus at least one older version.
• A parametrized test_a2a(<version>) session in py/noxfile.py, plus inclusion in .github/workflows/checks.yaml.
• Per-version cassette layout py/src/braintrust/integrations/a2a/cassettes/<version>/, and a corresponding [tool.braintrust.cassette-dirs] entry so py/scripts/check-stale-cassettes.py can detect orphans.
• Registration in auto_instrument() and a version gate consistent with py/src/braintrust/integrations/versioning.py.
• VCR-backed coverage of a client → server round trip, asserting the two sides share a root_span_id and that the server task span's span_parents contains the client delegation span's span_id. This is the test that actually proves the integration works; a single-sided test proves nothing about A2A.

---

Blocked on spec changes (braintrustdata/braintrust-spec)

1. No span type is defined for cross-process agent delegation.

The taxonomy in instrumentation-guide § Span types offers task ("a unit of application logic — an agent run, pipeline step, or named operation") and tool ("a model-initiated external call"). A client-side "call a remote agent" fits both partially and neither cleanly, and arguably the correct answer depends on the call site: a remote-agent call issued from inside a model tool-use loop is a tool; one issued by an orchestrator is a task. The spec must state the rule before any implementation can be judged conformant. This blocks Missing requirements #3.

2. No sanctioned metadata for protocol/RPC correlation identity.

A2A's taskId, contextId, remote agent name/URL, and skill id are the only fields that make a cross-process trace debuggable — without them a user cannot tell which remote agent a delegation span called, or correlate a Braintrust trace against A2A server logs. The metadata allowlist is closed (§ Data capturing policy), so these require an explicit allowlist extension. The guide does invite this: "It is encouraged to expand this specification for any data that may already be captured … however extensions of this specification should go through critical review." Without it the integration ships either non-conformant or unusable. This blocks Missing requirements #5.

3. time_to_first_token semantics on non-LLM streaming spans are undefined.

§ Streaming → Additional metrics defines it as "Seconds from request initiation to the first chunk received" and marks it MUST for streaming calls; the § Metrics Reference table scopes it to "Streaming spans" while scoping token metrics to "LLM spans". Whether an SSE-streamed task/tool span with no model behind it may — or must — emit time_to_first_token needs a ruling. This is the only metric an A2A streaming span could plausibly carry.

4. Suspended-and-resumed spans are not modeled.

A2A tasks can enter input-required or auth-required and resume minutes or days later, potentially from a different process after the original client span has closed. The spec has no notion of a span that pauses across a boundary and resumes. The two candidate shapes (close the span at suspension and link a fresh span on resume, vs. hold one long-lived span) have very different implications for metrics.end and for span export, and neither is specified.

5. No session/conversation grouping primitive above the trace.

A2A contextId groups many tasks — and therefore many independent traces — into one logical conversation. Braintrust's model has root_span_id per trace and no sanctioned cross-trace grouping key. Without one, a multi-turn A2A conversation fragments into N unrelated traces with no way to reassemble them.

---

Suggested edits to this issue

• Retitle the target. State up front that A2A is a transport/protocol integration, not a provider and not an agentic framework, that it emits zero llm spans, and that the § Canonical payload format OpenAI-Chat-Completions requirement therefore does not apply.
• Add a "Span structure" section. Server AgentExecutor.execute → task parent, holding the agent's own llm/tool children. Client message/send and message/stream → one delegation span each (type pending Blocked on spec changes feat: Remove all JS related code from this codebase #1). tasks/get / tasks/cancel → no span; fold terminal state into the originating client span.
• Add a "Distributed tracing" section and make it the issue's primary requirement. Cite features/distributed-tracing.md; specify inject-on-client and extract-on-server; enumerate the conformance cases (round trip, baggage 64-member/8192-byte caps with whole-member drops, braintrust.parent percent-encoding and prioritization, tracestate pass-through, lowercase/case-insensitive header handling, legacy-UUID no-op inject, missing/malformed traceparent → fresh root); point at the existing braintrust.propagation module, inject_trace_context, extract_trace_context, and Span.inject.
• Add explicit non-goals. The client MUST NOT synthesize child llm/tool spans for remote work. No duplicate agent-run span when both ends are instrumented.
• Define input / output concretely from Message.parts and the terminal Task/Message, and require in-place braintrust_attachment conversion for FilePart inline bytes, with remote uri parts logged as URLs.
• Add an explicit metadata/metrics statement. Emit nothing outside the guide's allowlist. Call out agent_card, agent_url, task_id, context_id, skill, task_state as blocked pending a braintrust-spec extension, and file that spec change as a tracked dependency of this issue.
• Add streaming and error-handling requirements. Single accumulated span across SSE, never one span per event. JSON-RPC errors and failed/rejected/canceled terminal states → top-level error.
• Require internal={"instrumentation": "a2a-auto"} so context.span_origin.instrumentation.name is populated, matching strands-auto / adk-auto.
• Add repo-mechanics acceptance criteria: [tool.braintrust.matrix] pins (latest + one older version), a test_a2a(<version>) nox session wired into .github/workflows/checks.yaml, per-version cassette directory, [tool.braintrust.cassette-dirs] entry, auto_instrument() registration, and a VCR-backed client→server round-trip test asserting shared root_span_id and correct span_parents.
• Mark this issue blocked on spec gaps feat: Remove all JS related code from this codebase #1 and feat(pydantic): Add tool call spans #2 above. Until the spec defines a span type for cross-process delegation and allowlists the protocol correlation metadata, there is no conformant shape to implement against.