Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: add enterprise A2A feature doc and update OSS A2A docs
Greyson LaLondeee049999cbf4
diff --git a/docs/docs.json b/docs/docs.jsonindex c175143ba..3f37157df 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -392,7 +392,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -865,7 +866,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -1338,7 +1340,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -1811,7 +1814,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -2283,7 +2287,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -2754,7 +2759,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -3225,7 +3231,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -3698,7 +3705,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -4169,7 +4177,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{@@ -4643,7 +4652,8 @@"en/enterprise/features/marketplace","en/enterprise/features/agent-repositories","en/enterprise/features/tools-and-integrations",- "en/enterprise/features/pii-trace-redactions"+ "en/enterprise/features/pii-trace-redactions",+ "en/enterprise/features/a2a"]},{diff --git a/docs/en/enterprise/features/a2a.mdx b/docs/en/enterprise/features/a2a.mdxnew file mode 100644index 000000000..0518743f4--- /dev/null+++ b/docs/en/enterprise/features/a2a.mdx@@ -0,0 +1,227 @@+---+title: A2A on AMP+description: Production-grade Agent-to-Agent communication with distributed state, multi-scheme authentication, and horizontal scaling+icon: "network-wired"+mode: "wide"+---++<Warning>+A2A server agents on AMP are in early release. APIs may change in future versions.+</Warning>++## Overview++CrewAI AMP extends the open-source [A2A protocol implementation](/en/learn/a2a-agent-delegation) with production infrastructure for deploying distributed agents at scale. AMP supports A2A protocol versions 0.2 and 0.3. When you deploy a crew or agent with A2A server configuration to AMP, the platform automatically provisions distributed state management, authentication, multi-transport endpoints, and lifecycle management.++<Note>+ For A2A protocol fundamentals, client/server configuration, and authentication schemes, see the [A2A Agent Delegation](/en/learn/a2a-agent-delegation) documentation. This page covers what AMP adds on top of the open-source implementation.+</Note>++### Usage++Add `A2AServerConfig` to any agent in your crew and deploy to AMP. The platform detects agents with server configuration and automatically registers A2A endpoints, generates agent cards, and provisions the infrastructure described below.++```python+from crewai import Agent, Crew, Task+from crewai.a2a import A2AServerConfig+from crewai.a2a.auth import EnterpriseTokenAuth++agent = Agent(+ role="Data Analyst",+ goal="Analyze datasets and provide insights",+ backstory="Expert data scientist with statistical analysis skills",+ llm="gpt-4o",+ a2a=A2AServerConfig(+ auth=EnterpriseTokenAuth()+ )+)++task = Task(+ description="Analyze the provided dataset",+ expected_output="Statistical summary with key insights",+ agent=agent+)++crew = Crew(agents=[agent], tasks=[task])+```++After [deploying to AMP](/en/enterprise/guides/deploy-to-amp), the platform registers two levels of A2A endpoints:++- **Crew-level**: an aggregate agent card at `/.well-known/agent-card.json` where each agent with `A2AServerConfig` is listed as a skill, with a JSON-RPC endpoint at `/a2a`+- **Per-agent**: isolated agent cards and JSON-RPC endpoints mounted at `/a2a/agents/{role}/`, each with its own tenancy++Clients can interact with the crew as a whole or target a specific agent directly. To route a request to a specific agent through the crew-level endpoint, include `"target_agent"` in the message metadata with the agent's slugified role name (e.g., `"data-analyst"` for an agent with role `"Data Analyst"`). If no `target_agent` is provided, the request is handled by the first agent in the crew.++See [A2A Agent Delegation](/en/learn/a2a-agent-delegation#server-configuration-options) for the full list of `A2AServerConfig` options.++<Warning>+ Per the A2A protocol, agent cards are publicly accessible to enable discovery. This includes both the crew-level card at `/.well-known/agent-card.json` and per-agent cards at `/a2a/agents/{role}/.well-known/agent-card.json`. Do not include sensitive information in agent names, descriptions, or skill definitions.+</Warning>++### File Inputs and Structured Output++A2A on AMP supports passing files and requesting structured output in both directions. Clients can send files as `FilePart`s and request structured responses by embedding a JSON schema in the message. Server agents receive files as `input_files` on the task, and return structured data as `DataPart`s when a schema is provided. See [File Inputs and Structured Output](/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details.++### What AMP Adds++<CardGroup cols={2}>+ <Card title="Distributed State" icon="database">+ Persistent task, context, and result storage that supports horizontal scaling+ </Card>+ <Card title="Enterprise Authentication" icon="shield-halved">+ OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens+ </Card>+ <Card title="gRPC Transport" icon="bolt">+ Full gRPC server with TLS and authentication+ </Card>+ <Card title="Context Lifecycle" icon="clock-rotate-left">+ Automatic idle detection, expiration, and cleanup of long-running conversations+ </Card>+ <Card title="Signed Webhooks" icon="signature">+ HMAC-SHA256 signed push notifications with replay protection+ </Card>+ <Card title="Multi-Transport" icon="arrows-split-up-and-left">+ REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment+ </Card>+</CardGroup>++---++## Distributed State Management++In the open-source implementation, task and context state lives in memory on a single process. AMP replaces this with persistent, distributed stores that enable horizontal scaling.++### Storage Layers++| Store | Purpose |+|---|---|+| **Task Store** | Persists A2A task state and metadata |+| **Context Store** | Tracks conversation context, creation time, last activity, and associated tasks |+| **Result Store** | Caches task results for retrieval |+| **Push Config Store** | Manages webhook subscriptions per task |++Multiple A2A deployments are automatically isolated from each other, preventing data collisions when sharing infrastructure.++---++## Enterprise Authentication++AMP supports six authentication schemes for incoming A2A requests, configurable per deployment. Authentication works across both HTTP and gRPC transports.++| Scheme | Description | Use Case |+|---|---|---|+| **SimpleTokenAuth** | Static bearer token from `AUTH_TOKEN` env var | Development, simple deployments |+| **EnterpriseTokenAuth** | Token verification via CrewAI PlusAPI with integration token claims | AMP-to-AMP agent communication |+| **OIDCAuth** | OpenID Connect JWT validation with JWKS endpoint caching | Enterprise SSO integration |+| **OAuth2ServerAuth** | OAuth2 with configurable scopes | Fine-grained access control |+| **APIKeyServerAuth** | API key validation via header or query parameter | Third-party integrations |+| **MTLSServerAuth** | Mutual TLS certificate-based authentication | Zero-trust environments |++The configured auth scheme automatically populates the agent card's `securitySchemes` and `security` fields. Clients discover authentication requirements by fetching the agent card before making requests.++---++## Extended Agent Cards++AMP supports role-based skill visibility through extended agent cards. Unauthenticated users see the standard agent card with public skills. Authenticated users receive an extended card with additional capabilities.++This enables patterns like:+- Public agents that expose basic skills to anyone, with advanced skills available to authenticated clients+- Internal agents that advertise different capabilities based on the caller's identity++---++## gRPC Transport++If enabled, AMP provides full gRPC support alongside the default JSON-RPC transport.++- **TLS termination** with configurable certificate and key paths+- **gRPC reflection** for debugging with tools like `grpcurl`+- **Authentication** using the same schemes available for HTTP+- **Extension validation** ensuring clients support required protocol extensions+- **Version negotiation** across A2A protocol versions 0.2 and 0.3++For deployments exposing multiple agents, AMP automatically allocates per-agent gRPC ports and coordinates TLS, startup, and shutdown across all servers.++---++## Context Lifecycle Management++AMP tracks the lifecycle of A2A conversation contexts and automatically manages cleanup.++### Lifecycle States++| State | Condition | Action |+|---|---|---|+| **Active** | Context has recent activity | None |+| **Idle** | No activity for a configured period | Marked idle, event emitted |+| **Expired** | Context exceeds its maximum lifetime | Marked expired, associated tasks cleaned up, event emitted |++A background cleanup task runs hourly to scan for idle and expired contexts. All state transitions emit CrewAI events that integrate with the platform's observability features.++---++## Signed Push Notifications++When an A2A agent sends push notifications to a client webhook, AMP signs each request with HMAC-SHA256 to ensure integrity and prevent tampering.++### Signature Headers++| Header | Purpose |+|---|---|+| `X-A2A-Signature` | HMAC-SHA256 signature in `sha256={hex_digest}` format |+| `X-A2A-Signature-Timestamp` | Unix timestamp bound to the signature |+| `X-A2A-Notification-Token` | Optional notification auth token |++### Security Properties++- **Integrity**: payload cannot be modified without invalidating the signature+- **Replay protection**: signatures are timestamp-bound with a configurable tolerance window+- **Retry with backoff**: failed deliveries retry with exponential backoff++---++## Distributed Event Streaming++In the open-source implementation, SSE streaming works within a single process. AMP propagates SSE events across instances so that clients receive updates even when the instance holding the streaming connection differs from the instance executing the task.++---++## Multi-Transport Endpoints++AMP serves REST and JSON-RPC by default. gRPC is available as an additional transport if enabled.++| Transport | Path Convention | Description |+|---|---|---|+| **REST** | `/v1/message:send`, `/v1/message:stream`, `/v1/tasks` | Google API conventions |+| **JSON-RPC** | Standard A2A JSON-RPC endpoint | Default A2A protocol transport |+| **gRPC** | Per-agent port allocation | Optional, high-performance binary protocol |++All active transports share the same authentication, version negotiation, and extension validation. Agent cards are generated from agent and crew metadata — roles, goals, and tools become skills and descriptions — and automatically include interfaces for each active transport. They can also be manually configured via `A2AServerConfig`.++---++## Version and Extension Negotiation++AMP validates A2A protocol versions and extensions at the transport layer.++### Version Negotiation++- Clients send the `A2A-Version` header with their preferred version+- AMP validates against supported versions (0.2, 0.3) and falls back to 0.3 if unspecified+- The negotiated version is returned in the response headers++### Extension Validation++- Clients declare supported extensions via the `X-A2A-Extensions` header+- AMP validates that clients support all extensions the agent requires+- Requests from clients missing required extensions receive an `UnsupportedExtensionError`++---++## Next Steps++- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration+- [A2UI](/en/learn/a2ui) — Interactive UI rendering over A2A+- [Deploy to AMP](/en/enterprise/guides/deploy-to-amp) — General deployment guide+- [Webhook Streaming](/en/enterprise/features/webhook-streaming) — Event streaming for deployed automationsdiff --git a/docs/en/learn/a2a-agent-delegation.mdx b/docs/en/learn/a2a-agent-delegation.mdxindex 942ca8bd0..4918e8754 100644--- a/docs/en/learn/a2a-agent-delegation.mdx+++ b/docs/en/learn/a2a-agent-delegation.mdx@@ -7,6 +7,10 @@ mode: "wide"## A2A Agent Delegation+<Info>+ Deploying A2A agents to production? See [A2A on AMP](/en/enterprise/features/a2a) for distributed state, enterprise authentication, gRPC transport, and horizontal scaling.+</Info>+CrewAI treats [A2A protocol](https://a2a-protocol.org/latest/) as a first-class delegation primitive, enabling agents to delegate tasks, request information, and collaborate with remote agents, as well as act as A2A-compliant server agents.In client mode, agents autonomously choose between local execution and remote delegation based on task requirements.@@ -96,24 +100,28 @@ The `A2AClientConfig` class accepts the following parameters:Update mechanism for receiving task status. Options: `StreamingConfig`, `PollingConfig`, or `PushNotificationConfig`.</ParamField>-<ParamField path="transport_protocol" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">- Transport protocol for A2A communication. Options: `JSONRPC` (default), `GRPC`, or `HTTP+JSON`.-</ParamField>-<ParamField path="accepted_output_modes" type="list[str]" default='["application/json"]'>Media types the client can accept in responses.</ParamField>-<ParamField path="supported_transports" type="list[str]" default='["JSONRPC"]'>- Ordered list of transport protocols the client supports.+<ParamField path="extensions" type="list[str]" default="[]">+ A2A protocol extension URIs the client supports.+</ParamField>++<ParamField path="client_extensions" type="list[A2AExtension]" default="[]">+ Client-side processing hooks for tool injection, prompt augmentation, and response modification.</ParamField>-<ParamField path="use_client_preference" type="bool" default="False">- Whether to prioritize client transport preferences over server.+<ParamField path="transport" type="ClientTransportConfig" default="ClientTransportConfig()">+ Transport configuration including preferred transport, supported transports for negotiation, and protocol-specific settings (gRPC message sizes, keepalive, etc.).</ParamField>-<ParamField path="extensions" type="list[str]" default="[]">- Extension URIs the client supports.+<ParamField path="transport_protocol" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="None">+ **Deprecated**: Use `transport=ClientTransportConfig(preferred=...)` instead.+</ParamField>++<ParamField path="supported_transports" type="list[str]" default="None">+ **Deprecated**: Use `transport=ClientTransportConfig(supported=...)` instead.</ParamField>## Authentication@@ -405,11 +413,7 @@ agent = Agent(Preferred endpoint URL. If set, overrides the URL passed to `to_agent_card()`.</ParamField>-<ParamField path="preferred_transport" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">- Transport protocol for the preferred endpoint.-</ParamField>--<ParamField path="protocol_version" type="str" default="0.3">+<ParamField path="protocol_version" type="str" default="0.3.0">A2A protocol version this agent supports.</ParamField>@@ -441,8 +445,36 @@ agent = Agent(Whether agent provides extended card to authenticated users.</ParamField>-<ParamField path="signatures" type="list[AgentCardSignature]" default="[]">- JSON Web Signatures for the AgentCard.+<ParamField path="extended_skills" type="list[AgentSkill]" default="[]">+ Additional skills visible only to authenticated users in the extended agent card.+</ParamField>++<ParamField path="signing_config" type="AgentCardSigningConfig" default="None">+ Configuration for signing the AgentCard with JWS. Supports RS256, ES256, PS256, and related algorithms.+</ParamField>++<ParamField path="server_extensions" type="list[ServerExtension]" default="[]">+ Server-side A2A protocol extensions with `on_request`/`on_response` hooks that modify agent behavior.+</ParamField>++<ParamField path="push_notifications" type="ServerPushNotificationConfig" default="None">+ Configuration for outgoing push notifications, including HMAC-SHA256 signing secret.+</ParamField>++<ParamField path="transport" type="ServerTransportConfig" default="ServerTransportConfig()">+ Transport configuration including preferred transport, gRPC server settings, JSON-RPC paths, and HTTP+JSON settings.+</ParamField>++<ParamField path="auth" type="ServerAuthScheme" default="None">+ Authentication scheme for incoming A2A requests. Defaults to `SimpleTokenAuth` using the `AUTH_TOKEN` environment variable.+</ParamField>++<ParamField path="preferred_transport" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="None">+ **Deprecated**: Use `transport=ServerTransportConfig(preferred=...)` instead.+</ParamField>++<ParamField path="signatures" type="list[AgentCardSignature]" default="None">+ **Deprecated**: Use `signing_config=AgentCardSigningConfig(...)` instead.</ParamField>### Combined Client and Server@@ -468,6 +500,14 @@ agent = Agent()```+### File Inputs and Structured Output++A2A supports passing files and requesting structured output in both directions.++**Client side**: When delegating to a remote A2A agent, files from the task's `input_files` are sent as `FilePart`s in the outgoing message. If `response_model` is set on the `A2AClientConfig`, the Pydantic model's JSON schema is embedded in the message metadata, requesting structured output from the remote agent.++**Server side**: Incoming `FilePart`s are extracted and passed to the agent's task as `input_files`. If the client included a JSON schema, the server creates a response model from it and applies it to the task. When the agent returns structured data, the response is sent back as a `DataPart` rather than plain text.+## Best Practices<CardGroup cols={2}>