diff --git a/docs/docs.json b/docs/docs.json index 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.mdx new file mode 100644 index 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" +--- + + +A2A server agents on AMP are in early release. APIs may change in future versions. + + +## 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. + + + 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. + + +### 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. + + + 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. + + +### 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 + + + + Persistent task, context, and result storage that supports horizontal scaling + + + OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens + + + Full gRPC server with TLS and authentication + + + Automatic idle detection, expiration, and cleanup of long-running conversations + + + HMAC-SHA256 signed push notifications with replay protection + + + REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment + + + +--- + +## 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 automations diff --git a/docs/en/learn/a2a-agent-delegation.mdx b/docs/en/learn/a2a-agent-delegation.mdx index 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 + + Deploying A2A agents to production? See [A2A on AMP](/en/enterprise/features/a2a) for distributed state, enterprise authentication, gRPC transport, and horizontal scaling. + + 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`. - - Transport protocol for A2A communication. Options: `JSONRPC` (default), `GRPC`, or `HTTP+JSON`. - - Media types the client can accept in responses. - - Ordered list of transport protocols the client supports. - - - - Whether to prioritize client transport preferences over server. - - - Extension URIs the client supports. + A2A protocol extension URIs the client supports. + + + + Client-side processing hooks for tool injection, prompt augmentation, and response modification. + + + + Transport configuration including preferred transport, supported transports for negotiation, and protocol-specific settings (gRPC message sizes, keepalive, etc.). + + + + **Deprecated**: Use `transport=ClientTransportConfig(preferred=...)` instead. + + + + **Deprecated**: Use `transport=ClientTransportConfig(supported=...)` instead. ## Authentication @@ -405,11 +413,7 @@ agent = Agent( Preferred endpoint URL. If set, overrides the URL passed to `to_agent_card()`. - - Transport protocol for the preferred endpoint. - - - + A2A protocol version this agent supports. @@ -441,8 +445,36 @@ agent = Agent( Whether agent provides extended card to authenticated users. - - JSON Web Signatures for the AgentCard. + + Additional skills visible only to authenticated users in the extended agent card. + + + + Configuration for signing the AgentCard with JWS. Supports RS256, ES256, PS256, and related algorithms. + + + + Server-side A2A protocol extensions with `on_request`/`on_response` hooks that modify agent behavior. + + + + Configuration for outgoing push notifications, including HMAC-SHA256 signing secret. + + + + Transport configuration including preferred transport, gRPC server settings, JSON-RPC paths, and HTTP+JSON settings. + + + + Authentication scheme for incoming A2A requests. Defaults to `SimpleTokenAuth` using the `AUTH_TOKEN` environment variable. + + + + **Deprecated**: Use `transport=ServerTransportConfig(preferred=...)` instead. + + + + **Deprecated**: Use `signing_config=AgentCardSigningConfig(...)` instead. ### 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