diff --git a/docs/en/learn/a2a-agent-delegation.mdx b/docs/en/learn/a2a-agent-delegation.mdx index 174939e3d..942ca8bd0 100644 --- a/docs/en/learn/a2a-agent-delegation.mdx +++ b/docs/en/learn/a2a-agent-delegation.mdx @@ -1,43 +1,48 @@ --- title: Agent-to-Agent (A2A) Protocol -description: Enable CrewAI agents to delegate tasks to remote A2A-compliant agents for specialized handling +description: Agents delegate tasks to remote A2A agents and/or operate as A2A-compliant server agents. icon: network-wired mode: "wide" --- ## A2A Agent Delegation -CrewAI supports the Agent-to-Agent (A2A) protocol, allowing agents to delegate tasks to remote specialized agents. The agent's LLM automatically decides whether to handle a task directly or delegate to an A2A agent based on the task requirements. - - - A2A delegation requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'` - +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. ## How It Works When an agent is configured with A2A capabilities: -1. The LLM analyzes each task +1. The Agent analyzes each task 2. It decides to either: - Handle the task directly using its own capabilities - Delegate to a remote A2A agent for specialized handling 3. If delegating, the agent communicates with the remote A2A agent through the protocol 4. Results are returned to the CrewAI workflow + + A2A delegation requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'` + + ## Basic Configuration + + `crewai.a2a.config.A2AConfig` is deprecated and will be removed in v2.0.0. Use `A2AClientConfig` for connecting to remote agents and/or `A2AServerConfig` for exposing agents as servers. + + Configure an agent for A2A delegation by setting the `a2a` parameter: ```python Code from crewai import Agent, Crew, Task -from crewai.a2a import A2AConfig +from crewai.a2a import A2AClientConfig agent = Agent( role="Research Coordinator", goal="Coordinate research tasks efficiently", backstory="Expert at delegating to specialized research agents", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://example.com/.well-known/agent-card.json", timeout=120, max_turns=10 @@ -54,9 +59,9 @@ crew = Crew(agents=[agent], tasks=[task], verbose=True) result = crew.kickoff() ``` -## Configuration Options +## Client Configuration Options -The `A2AConfig` class accepts the following parameters: +The `A2AClientConfig` class accepts the following parameters: The A2A agent endpoint URL (typically points to `.well-known/agent-card.json`) @@ -95,14 +100,30 @@ The `A2AConfig` class accepts the following parameters: 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. + + ## Authentication For A2A agents that require authentication, use one of the provided auth schemes: - ```python Code -from crewai.a2a import A2AConfig +```python bearer_token_auth.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.auth import BearerTokenAuth agent = Agent( @@ -110,18 +131,18 @@ agent = Agent( goal="Coordinate tasks with secured agents", backstory="Manages secure agent communications", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://secure-agent.example.com/.well-known/agent-card.json", auth=BearerTokenAuth(token="your-bearer-token"), timeout=120 ) ) - ``` +``` - ```python Code -from crewai.a2a import A2AConfig +```python api_key_auth.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.auth import APIKeyAuth agent = Agent( @@ -129,7 +150,7 @@ agent = Agent( goal="Coordinate with API-based agents", backstory="Manages API-authenticated communications", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://api-agent.example.com/.well-known/agent-card.json", auth=APIKeyAuth( api_key="your-api-key", @@ -139,12 +160,12 @@ agent = Agent( timeout=120 ) ) - ``` +``` - ```python Code -from crewai.a2a import A2AConfig +```python oauth2_auth.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.auth import OAuth2ClientCredentials agent = Agent( @@ -152,7 +173,7 @@ agent = Agent( goal="Coordinate with OAuth-secured agents", backstory="Manages OAuth-authenticated communications", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://oauth-agent.example.com/.well-known/agent-card.json", auth=OAuth2ClientCredentials( token_url="https://auth.example.com/oauth/token", @@ -163,12 +184,12 @@ agent = Agent( timeout=120 ) ) - ``` +``` - ```python Code -from crewai.a2a import A2AConfig +```python http_basic_auth.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.auth import HTTPBasicAuth agent = Agent( @@ -176,7 +197,7 @@ agent = Agent( goal="Coordinate with basic auth agents", backstory="Manages basic authentication communications", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://basic-agent.example.com/.well-known/agent-card.json", auth=HTTPBasicAuth( username="your-username", @@ -185,7 +206,7 @@ agent = Agent( timeout=120 ) ) - ``` +``` @@ -194,7 +215,7 @@ agent = Agent( Configure multiple A2A agents for delegation by passing a list: ```python Code -from crewai.a2a import A2AConfig +from crewai.a2a import A2AClientConfig from crewai.a2a.auth import BearerTokenAuth agent = Agent( @@ -203,11 +224,11 @@ agent = Agent( backstory="Expert at delegating to the right specialist", llm="gpt-4o", a2a=[ - A2AConfig( + A2AClientConfig( endpoint="https://research.example.com/.well-known/agent-card.json", timeout=120 ), - A2AConfig( + A2AClientConfig( endpoint="https://data.example.com/.well-known/agent-card.json", auth=BearerTokenAuth(token="data-token"), timeout=90 @@ -223,7 +244,7 @@ The LLM will automatically choose which A2A agent to delegate to based on the ta Control how agent connection failures are handled using the `fail_fast` parameter: ```python Code -from crewai.a2a import A2AConfig +from crewai.a2a import A2AClientConfig # Fail immediately on connection errors (default) agent = Agent( @@ -231,7 +252,7 @@ agent = Agent( goal="Coordinate research tasks", backstory="Expert at delegation", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://research.example.com/.well-known/agent-card.json", fail_fast=True ) @@ -244,11 +265,11 @@ agent = Agent( backstory="Expert at working with available resources", llm="gpt-4o", a2a=[ - A2AConfig( + A2AClientConfig( endpoint="https://primary.example.com/.well-known/agent-card.json", fail_fast=False ), - A2AConfig( + A2AClientConfig( endpoint="https://backup.example.com/.well-known/agent-card.json", fail_fast=False ) @@ -267,8 +288,8 @@ Control how your agent receives task status updates from remote A2A agents: - ```python Code -from crewai.a2a import A2AConfig +```python streaming_config.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.updates import StreamingConfig agent = Agent( @@ -276,17 +297,17 @@ agent = Agent( goal="Coordinate research tasks", backstory="Expert at delegation", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://research.example.com/.well-known/agent-card.json", updates=StreamingConfig() ) ) - ``` +``` - ```python Code -from crewai.a2a import A2AConfig +```python polling_config.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.updates import PollingConfig agent = Agent( @@ -294,7 +315,7 @@ agent = Agent( goal="Coordinate research tasks", backstory="Expert at delegation", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://research.example.com/.well-known/agent-card.json", updates=PollingConfig( interval=2.0, @@ -303,12 +324,12 @@ agent = Agent( ) ) ) - ``` +``` - ```python Code -from crewai.a2a import A2AConfig +```python push_notifications_config.py lines +from crewai.a2a import A2AClientConfig from crewai.a2a.updates import PushNotificationConfig agent = Agent( @@ -316,19 +337,137 @@ agent = Agent( goal="Coordinate research tasks", backstory="Expert at delegation", llm="gpt-4o", - a2a=A2AConfig( + a2a=A2AClientConfig( endpoint="https://research.example.com/.well-known/agent-card.json", updates=PushNotificationConfig( - url={base_url}/a2a/callback", + url="{base_url}/a2a/callback", token="your-validation-token", timeout=300.0 ) ) ) - ``` +``` +## Exposing Agents as A2A Servers + +You can expose your CrewAI agents as A2A-compliant servers, allowing other A2A clients to delegate tasks to them. + +### Server Configuration + +Add an `A2AServerConfig` to your agent to enable server capabilities: + +```python a2a_server_agent.py lines +from crewai import Agent +from crewai.a2a import A2AServerConfig + +agent = Agent( + role="Data Analyst", + goal="Analyze datasets and provide insights", + backstory="Expert data scientist with statistical analysis skills", + llm="gpt-4o", + a2a=A2AServerConfig(url="https://your-server.com") +) +``` + +### Server Configuration Options + + + Human-readable name for the agent. Defaults to the agent's role if not provided. + + + + Human-readable description. Defaults to the agent's goal and backstory if not provided. + + + + Version string for the agent card. + + + + List of agent skills. Auto-generated from agent tools if not provided. + + + + Declaration of optional capabilities supported by the agent. + + + + Supported input MIME types. + + + + Supported output MIME types. + + + + 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. + + + + Information about the agent's service provider. + + + + URL to the agent's documentation. + + + + URL to an icon for the agent. + + + + Additional supported interfaces (transport and URL combinations). + + + + Security requirement objects for all agent interactions. + + + + Security schemes available to authorize requests. + + + + Whether agent provides extended card to authenticated users. + + + + JSON Web Signatures for the AgentCard. + + +### Combined Client and Server + +An agent can act as both client and server by providing both configurations: + +```python Code +from crewai import Agent +from crewai.a2a import A2AClientConfig, A2AServerConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research and serve analysis requests", + backstory="Expert at delegation and analysis", + llm="gpt-4o", + a2a=[ + A2AClientConfig( + endpoint="https://specialist.example.com/.well-known/agent-card.json", + timeout=120 + ), + A2AServerConfig(url="https://your-server.com") + ] +) +``` + ## Best Practices diff --git a/lib/crewai/src/crewai/a2a/__init__.py b/lib/crewai/src/crewai/a2a/__init__.py index 288e805f6..634f77708 100644 --- a/lib/crewai/src/crewai/a2a/__init__.py +++ b/lib/crewai/src/crewai/a2a/__init__.py @@ -1,8 +1,10 @@ """Agent-to-Agent (A2A) protocol communication module for CrewAI.""" -from crewai.a2a.config import A2AConfig +from crewai.a2a.config import A2AClientConfig, A2AConfig, A2AServerConfig __all__ = [ + "A2AClientConfig", "A2AConfig", + "A2AServerConfig", ]