A2A Protocol in Python: A Practical Guide to Agent Interoperability

A2A gives a client agent a standard way to discover a remote agent's declared capabilities, send it a message, track task progress, and receive a result. The two agents can be built with different frameworks or model providers. The remote agent remains responsible for its own execution and can keep its internal prompts, memory, tools, and implementation private.

A2A standardizes the interaction boundary, not the quality of the remote agent's decisions. It does not make an untrusted agent safe, guarantee a task will finish, or remove the need to define success. Your application still needs timeouts, authorization, validation, retry rules, and a human escalation path for consequential actions.

If you are still designing a single agent before exposing it remotely, start with our production AI-agent guide; A2A is most useful after there is a real boundary between independently managed components.

A2A and the Model Context Protocol (MCP) solve different integration problems. MCP is commonly used when an agent needs structured access to tools, APIs, or resources. A2A is for communication with another agent that owns its own task logic and may collaborate over several steps. An agent framework helps build and orchestrate an agent; it is not a replacement for either protocol.

A useful architecture can use all three: a framework runs the local agent, MCP connects it to tools, and A2A lets it delegate a bounded task to a remote agent. Avoid adding a protocol just because it is popular. A direct function call or ordinary HTTP API is often simpler when both components are deployed together and have a narrow contract.

For the tool-facing side of this architecture, compare our Google Cloud API Gateway MCP analysis and WebMCP guide; those cover different boundaries from remote agent collaboration.

An Agent Card describes an A2A server's identity, skills, supported input/output media types, protocol interfaces, and declared capabilities such as streaming. The official Python quickstart uses `/.well-known/agent-card.json` as the default discovery endpoint, although a deployment can configure another path.

Treat the card as a discovery document, not proof that the server is trustworthy or that every advertised skill is available to every caller. Cards can be stale, endpoints can change, and a skill description cannot replace runtime validation. Resolve endpoints through trusted configuration or discovery policy, verify server identity, and test the contract your application expects.

Keep skill descriptions concrete: state the task, accepted inputs, expected output, examples, and limitations. Precise declarations make routing and contract tests easier than vague claims such as 'handles any business workflow'.

An agent task may involve retrieval, model calls, tools, retries, or human review. A2A's task-oriented model lets the server communicate status and results while work progresses. The client can distinguish 'accepted and still working' from 'completed with an artifact' or 'failed and needs recovery'.

Streaming is useful when the caller needs progress or incremental updates. It also creates operational responsibilities: clients must handle disconnects, partial results, tasks that outlive the original HTTP connection, and duplicate submissions after uncertain failures. If the caller only needs a final value, start with non-streaming behavior until measurements justify the extra complexity.

The official Python quickstart demonstrates a discovery-first flow: fetch the remote Agent Card, create a client from the card, build a user message, and send it through the SDK. The example below follows that API shape and assumes a compatible test server is already running at the supplied base URL.

This is an illustrative client pattern, not a complete production integration. It intentionally omits authentication configuration, application-specific result parsing, retries, and deployment setup. Check the pinned SDK version's docs and sample application before copying it into a service.

The SDK's `AgentExecutor` interface is where application-specific work runs. The current Python tutorial defines asynchronous `execute` and `cancel` methods and uses an event queue to send task status and artifacts back to the protocol layer. This is a useful seam: the executor can call an existing workflow while the SDK handles the protocol interaction.

Separate input validation, authorization, task orchestration, side-effecting tools, and output validation. That makes it possible to test business logic without a network and to test the protocol adapter with a fake executor.

Define cancellation before exposing it. Cancelling a request does not reverse an email already sent, purchase already placed, or database write already committed. For side-effecting tasks, use idempotency controls in the application and compensating actions where rollback is possible.

The A2A specification relies on familiar web-security practices: encrypted transport, server identity verification, and authentication/authorization appropriate to the deployment. Clients can discover declared security schemes through the card, but credentials should be obtained through a trusted process and checked by the server. A protocol-level description does not grant permission to execute a privileged action.

The main risk is confused authority. A remote agent can return plausible but incorrect instructions, and an authenticated caller may still request an action outside its business role. Enforce authorization at the receiving service and again at the resource or tool that performs the side effect. Treat remote output as untrusted input until validated.

Set an overall deadline for the business task and separate timeouts for discovery, connection, and execution. A retry is safe only when the operation is idempotent or duplicate work can be detected. If a connection drops after submission, build a recovery path that can find the existing task instead of blindly submitting a second copy.

For traces, latency, and sensitive-payload handling across model calls and tools, see our OpenTelemetry observability blueprint. Carry a correlation or task ID across the boundary, but keep prompt and artifact contents out of telemetry unless a reviewed policy requires them.

A2A is a strong candidate when teams operate agents independently, need to preserve separate implementation and data boundaries, or must exchange progress and artifacts for long-running tasks. It can reduce bespoke point-to-point adapters, but it cannot eliminate domain-specific contracts, identity management, operational ownership, or acceptance tests.

For a single application with one deployment and a short deterministic operation, a local function or conventional API may be easier to secure and operate. Start with the smallest interface that meets the requirement, then introduce A2A when independent agent ownership or task semantics justify the extra moving parts.

Start with one low-risk skill that has a clear input schema, a predictable output artifact, and no irreversible side effects. Run the official sample locally, then replace the demo executor with a small adapter around a real workflow. Measure discovery success, task completion, latency, and error recovery before adding streaming or more agents.

In staging, test authenticated and unauthorized callers, stale Agent Cards, malformed inputs, remote timeouts, streaming disconnects, duplicate requests, and cancellation. Review logs for accidental payload capture. Only after these checks pass should you add a write-capable skill. The milestone is not merely that two agents can talk; it is that the system can constrain, observe, validate, and recover from what they do.