A2A Protocol Best Practices: Production Guide

Written by: Mariana Fonseca, Editorial Team, AI Growth Agent

Key Takeaways for Production A2A

• The A2A protocol enables secure, structured collaboration between autonomous AI agents across platforms without exposing internal state or tools.
• Production deployments require accurate Agent Cards at /.well-known/agent-card.json, declared authentication schemes, and zero-trust enforcement at every boundary.
• Key operational rules include input sanitization, task immutability after terminal states, contextId continuity, and separation of artifacts from messages.
• Teams must distinguish A2A (agent orchestration) from MCP (tool access), implement SSE for long-running tasks, and avoid common anti-patterns like stale cards or long-lived tokens.
• AI Growth Agent helps engineering teams maintain accurate, up-to-date A2A documentation as specifications evolve—see how living content keeps your multi-agent systems reliable.

A2A Protocol Security in Production

A2A security architecture stays identity-centric, delegation-aware, and continuously validated. The protocol does not implement authentication itself, and it instead advertises authentication requirements via the AgentCard while enterprise identity providers and API gateways enforce them.

Supported authentication schemes include API keys, OAuth2, and mutual TLS (mTLS). For production deployments, OAuth 2.1 with PKCE and short-lived JWTs with strict audience claims provides a strong current baseline.

Authentication tokens for A2A communication must carry a defined set of claims. Required fields include:

• Subject (AI agent identity)
• Audience (target agent or service)
• Scope (authorized actions)
• Tenant identifier
• Expiration timestamp
• Delegation metadata when applicable

These token claims form the foundation of A2A authentication, yet production systems need more than static token checks. Zero-trust enhancements extend beyond token validation and feed Remote Attestation Results, OpenTelemetry telemetry, and microsegmentation policies into a Policy Decision Point for real-time posture assessment and lateral-movement prevention. The Master Agent acts as an OAuth 2.1 resource server and Policy Enforcement Point, querying a PDP that supports RBAC, ABAC, or ReBAC models before enforcing fine-grained access decisions.

Authorization creep appears as the most common security failure in A2A deployments. Authorization checks can occur too late when a remote agent defers permission decisions until after accepting a task. The mitigation is clear: enforce scope validation at the API gateway before task creation, not inside the agent executor.

Input sanitization is non-negotiable because a remote agent’s internal reasoning remains opaque to the client. This opacity means every inbound message must be treated as untrusted and validated against expected schema before processing. Prompt injection is a documented threat vector, so agents should not have direct access to secrets and must obtain only temporary access tokens through a secure API or trusted intermediary.

Teams shipping A2A orchestration this sprint can get a structured security posture review from AI Growth Agent and see how authoritative A2A security content stays aligned with the specification.

Accurate Agent Cards and Discovery Hygiene

The Agent Card forms the foundation of A2A interoperability. It functions as a machine-readable digital résumé that advertises an agent’s capabilities, endpoint URL, required authentication methods, and input or output expectations.

Required fields per the A2A Agent Card JSON Schema include:

• name and description
• url (the reachable HTTPS endpoint)
• version
• capabilities (such as streaming support)
• skills with id, name, and description

A2A Agent Cards must be hosted at /.well-known/agent-card.json per RFC 8615. The A2A specification also references /.well-known/agent-card.json as the hosting path, so teams should validate which path the framework resolver queries and publish to both if necessary during the transition to the 1.0 specification.

The separation between public and private cards protects security, not just organization. Public agent cards expose discoverable capabilities while private agent cards contain sensitive configuration protected by authentication. Never include internal routing details, database connection strings, or internal service URLs in a public card.

Once you establish proper separation between public and private cards, the next challenge is keeping both versions synchronized with the live deployment. The architecture for Agent Card separation follows a clear pattern:

• Public card at /.well-known/agent.json: capabilities, skills, endpoint URL, supported authentication schemes
• Private card (authenticated endpoint): operational limits, internal skill configurations, environment-specific parameters
• API gateway: enforces authentication before serving the private card
• Orchestrator: resolves the public card first, then authenticates to retrieve extended capability details if needed

Stale Agent Cards cause many orchestration failures in production. Version-stamp every card and automate validation on deployment. The A2A Java SDK 1.0.0.Alpha1 aligns AgentCard with the 1.0 specification by replacing separate url, preferredTransport, and additionalInterfaces fields with a supportedInterfaces list, which makes automated card checks on each SDK upgrade essential.

Keeping Agent Card documentation accurate at enterprise scale fits AI Growth Agent’s living technical content model, and teams can see how the platform generates, validates, and updates these references as specifications change.

Async Workloads and Streaming Patterns

A2A supports long-running tasks as a first-class concern. Tasks may complete immediately or span hours, and the protocol provides native streaming through Server-Sent Events so clients receive progress updates without holding synchronous connections.

The SSE subscription pattern uses streaming endpoints, and clients receive task status and artifact update streams as the task moves through its lifecycle states. The eight explicit task lifecycle states are submitted, working, input_required, auth_required, completed, failed, canceled, and rejected.

Webhook push notifications complement SSE when the client cannot maintain a persistent connection. Teams configure push notification endpoints in the Agent Card capabilities field, and the receiving endpoint must validate the notification signature before processing.

Framework-specific patterns for production deployments vary with each framework’s architectural model. LangGraph emphasizes event-driven execution, BeeAI focuses on capability-based discovery, and Vertex AI relies on dynamic agent resolution:

• LangGraph: LangGraph agents communicate with A2A peers solely through A2A messages, tasks, and artifacts without sharing internal code. Implement the AgentExecutor subclass pattern, enqueue a completed_task event containing a new_artifact with typed Parts, and preserve task immutability by never modifying the original task object after the executor returns.
• BeeAI: BeeAI’s framework-agnostic design aligns with A2A’s protocol-first orchestration model. Use capability declarations such as task-analyzer, knowledge-retriever, and response-generator in the Agent Card skills field to enable dynamic discovery by an A2A orchestrator.
• Vertex AI / Google ADK: Use the before_agent_callback hook to discover remote Agent Cards via A2ACardResolver, store RemoteAgentConnections keyed by card.name, and inject the list of discovered agents into the root instruction prompt so the orchestrator knows remote capabilities without hard-coded knowledge.

Non-blocking operations depend on explicit task state management. Return a submitted state immediately on task creation, transition to working when processing begins, and emit artifact update events as outputs become available instead of batching all results at completion.

Teams building async A2A pipelines can use AI Growth Agent to keep framework-specific runbooks aligned with current patterns and see how living content supports evolving async architectures.

Coordinating A2A and MCP

A2A and MCP solve different architectural problems and work best together. Rob Barton, Distinguished AI Engineer at Cisco, compares the relationship to Layer-2 and Layer-3 networking: MCP provides detailed tool-level visibility while A2A provides scalable agent-level routing.

Dimension	A2A	MCP	Recommended Use
Architecture	Many-to-many client-server enabling mesh topologies	Hub-and-spoke: MCP Host connects to tool servers	Use both layers together in multi-agent systems
Primary purpose	Agent-to-agent delegation, coordination, and orchestration	Standardized tool, data, and external system access	A2A for orchestration, MCP for tool integration
Discovery mechanism	Agent Cards at /.well-known/agent-card.json with built-in lifecycle management	Tool descriptions in LLM context window; scalability limited by context size	A2A for agent discovery, MCP for tool enumeration
Security focus	Signed agent cards, capability restrictions, task isolation, authenticated push notifications	Confused deputy prevention, token pass-through risks, SSRF, session hijacking via OAuth 2.1	Apply distinct security models at each layer

The recommended separation of concerns in production keeps orchestration and tool access distinct. A planner agent reaches out to other agents via A2A while those agents use MCP internally to fetch tools. A practical example is a support orchestrator using A2A to delegate billing queries and refund approvals to specialized agents that internally use MCP to access CRM systems, policy repositories, and shipping APIs.

Engineering teams documenting A2A and MCP separation for architecture reviews can see how AI Growth Agent’s living technical content platform keeps this documentation aligned as both specifications evolve.

Common A2A Anti-Patterns

Several failure modes appear consistently in A2A production deployments and cause many orchestration failures, security incidents, and debugging hours.

• Task mutation after terminal state. Attempting to restart or modify a completed, canceled, rejected, or failed task breaks reliable traceability and predictable client orchestration. Always create a new task under the same contextId.
• Inaccurate or stale Agent Cards. Publishing capability declarations that do not match the agent’s actual skills, endpoints, or authentication requirements causes orchestrators to route tasks incorrectly and produces failures that are difficult to trace. Automate card validation on every deployment.
• Conflating A2A with MCP. Using MCP where A2A is required, or the reverse, creates architectural coupling that harms both security and maintainability. The protocols operate at different layers and require distinct security models.
• Skipping input sanitization. Treating messages from peer agents as trusted because they arrived over an authenticated channel ignores the prompt injection threat vector. Every inbound message must be validated against expected schema regardless of the sender’s authentication status.
• Long-lived tokens. Using long-lived tokens, failing tenant matching, or skipping delegation validation are explicit anti-patterns in A2A communication. Tokens must carry expiration timestamps and delegation metadata.
• Skipping orchestrator agent patterns for complex workflows. Failing to use orchestrator agents for task decomposition and distributed state management in complex multi-agent workflows is a documented production anti-pattern.
• Not testing with representative workflows. Benchmarking performance under unrealistic loads or ignoring SDK maturity evaluation for the target technology stack produces systems that fail under production conditions.

Teams auditing their A2A implementations against these failure modes can use AI Growth Agent to keep runbooks and architecture guides aligned with current guidance and see how automated content generation supports ongoing A2A reviews.

Task Immutability and Artifact Separation

Task immutability functions as a core A2A design principle rather than an implementation detail. Once a task reaches a terminal state, it cannot be restarted, and any modifications or follow-ups must create a new task under the same contextId. This rule preserves reliable referencing, clear input-output mapping, and elimination of restart ambiguity.

The contextId is a server-generated identifier that groups related Task and Message objects. Clients refine previous task results by starting a new interaction under the same contextId and optionally referencing earlier tasks using referenceTaskIds, and the server typically responds with a new Task or a Message if it can complete immediately.

Artifact separation enforces a clean boundary between conversational negotiation and final deliverables. Artifacts are immutable outputs including documents, images, and structured data that attach to completed task results as named artifacts containing typed parts with mimeType and bytes fields. Versioned outputs across follow-up tasks under the same contextId receive native support.

Structured error handling follows a defined pattern. Wrap agent invocation failures in ServerError(error=ValueError(...)) and raise UnsupportedOperationError() from the cancel method when cancellation is not supported. Never surface internal stack traces or reasoning chain details in error responses returned to client agents.

The specification defines a clear decision between returning a Message or a Task. Return stateless Message responses for trivial or transactional interactions such as negotiation, clarification, or quick answers, and stateful Task objects for any work that benefits from status tracking, retries, resubscription, or artifact production.

Teams building production A2A systems and needing documentation that reflects these lifecycle rules accurately can see how AI Growth Agent’s living content platform encodes these patterns into your internal guides.

Versioning, Idempotency, and Framework Integration

A2A versioning operates at two levels: the protocol version declared in the Agent Card and the agent’s own capability version. Include both version and protocolVersion fields in every Agent Card and update them on each breaking change to capability declarations or skill interfaces. The Java SDK breaking change described earlier shows why version-stamping remains non-negotiable in production.

Idempotency does not come natively from the protocol. Task delivery semantics require manual implementation of idempotency, retry coordination, and ordering. The standard pattern generates a deterministic task ID from the input payload hash and checks for an existing task with that ID before creating a new one.

Framework integration patterns for the three most common production stacks include:

• LangGraph: Implement the AgentExecutor subclass. The execute method invokes the underlying LangGraph agent, then enqueues a completed_task event containing a new_artifact with typed Parts and the original message. LangGraph agents communicate with A2A peers solely through A2A messages, tasks, and artifacts without sharing internal code or requiring the same language or deployment target.
• BeeAI: Publish capability declarations in the Agent Card skills field using descriptive identifiers. Examples include task-analyzer for a planner, knowledge-retriever for a researcher, and response-generator for a synthesizer, which enables dynamic discovery by an A2A orchestrator without hard-coded routing logic.
• Vertex AI / Google ADK: Use A2ACardResolver in the before_agent_callback to resolve remote Agent Cards at startup. Store RemoteAgentConnections keyed by card.name and inject the discovered agent list into the root instruction. When sending tasks, improve task descriptions with full necessary context because remote agents lack the user’s conversation history.

Teams that rely on static documentation will see their runbooks drift within weeks of a major SDK release. AI Growth Agent’s living content platform automatically regenerates and validates technical documentation as specifications change, and you can review how this behaves at enterprise scale.

Conclusion: Ship Reliable A2A Orchestration This Sprint

The practices in this guide cover the main production surface for A2A deployments, including accurate Agent Cards hosted at /.well-known/agent-card.json, zero-trust authentication with short-lived tokens and strict audience claims, and input sanitization at every agent boundary.