a2a-setup.md · samitouri/QOSami_Agents_Zero-2

Code Commits Issues Pulls Sessions CI/CD

main

md 153 lines 4.82 KB

Rendered Raw

1	# A2A Server Setup
2
3	Agent Zero can communicate with other Agent Zero instances using the A2A (Agent-to-Agent) protocol based on FastA2A. This guide shows you how to enable and configure A2A connectivity through the Settings UI.
4
5	## What is A2A?
6
7	A2A enables direct communication between multiple Agent Zero instances. This allows:
8
9	- Distributed workflows - Delegate tasks to specialized agent instances
10	- Context isolation - Maintain separate workspaces for different agents
11	- Long-running collaboration - Persistent agent-to-agent conversations
12	- Project-specific delegation - Route work to agents with specific project contexts
13
14	> [!NOTE]
15	> This guide covers enabling Agent Zero as an A2A server. For API-level integration details, see the [advanced connectivity documentation](../developer/connectivity.md).
16
17	## Enabling the A2A Server
18
19	### Step 1: Open A2A Configuration
20
21	1. Click Settings in the sidebar
22	2. Navigate to the MCP/A2A tab
23	3. Scroll to the A0 A2A Server section
24	4. Toggle Enable A2A server to ON
25
26	![A2A Server Settings](../res/setup/a2a/a2a-conn.png)
27
28	### Step 2: Get Connection URL
29
30	1. Click on connection example to view your A2A connection details
31	2. The dialog displays:
32	- API Token - Automatically generated from your username and password
33	- A2A Connection URL - The full URL other agents will use to connect
34	- Optional Project selector - To create project-specific connection URLs
35
36	![A2A Connection Dialog](../res/setup/a2a/a2a2.png)
37
38	### Step 3: Save Configuration
39
40	1. Click Save to apply your settings
41	2. The A2A server is now active and ready to accept connections
42
43	> [!IMPORTANT]
44	> The API token changes when you update your Agent Zero credentials. Existing connections will need to be reconfigured with the new token.
45
46	## Connection URL Format
47
48	The basic A2A connection URL follows this format:
49
50	```
51	http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN
52	```
53
54	### With Project Context
55
56	To connect with a specific project active:
57
58	```
59	http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN/p-PROJECT_NAME
60	```
61
62	When a project is specified:
63	- All A2A conversations run in that project's context
64	- The agent has access to project-specific resources and knowledge
65	- Enables isolated, project-focused agent collaboration
66
67	## Example Use Cases
68
69	### 1. Local Development Setup
70
71	Two Agent Zero instances on the same machine:
72
73	```
74	Instance 1: http://localhost:8080/a2a/t-abc123xyz
75	Instance 2: http://localhost:8081/a2a/t-def456uvw
76	```
77
78	### 2. Remote Agent Collaboration
79
80	Connect to a remote Agent Zero instance:
81
82	```
83	http://agent.example.com:8080/a2a/t-remote-token
84	```
85
86	### 3. Project-Specific Delegation
87
88	Main agent delegates frontend work to specialized agent:
89
90	```
91	http://localhost:8081/a2a/t-frontend-token/p-webapp-ui
92	```
93
94	## Docker Networking
95
96	If running Agent Zero in Docker:
97
98	- Same Host: Use `host.docker.internal:PORT` (macOS/Windows) or container networking (Linux)
99	- Different Hosts: Use the public IP or domain name of the target instance
100	- Port Mapping: Ensure the Agent Zero port is exposed in your Docker configuration
101
102	## Security Considerations
103
104	- Token Protection: Keep your API tokens secure - they provide full access to your Agent Zero instance
105	- Network Access: Consider using firewalls or reverse proxies to restrict A2A endpoint access
106	- HTTPS: For production deployments, use HTTPS to encrypt A2A communication
107	- Credential Rotation: Changing your password will invalidate all existing A2A connection URLs
108
109	## Testing Your Connection
110
111	You can test A2A connectivity using curl:
112
113	```bash
114	curl -X POST http://localhost:8080/a2a/t-YOUR_TOKEN \
115	-H "Content-Type: application/json" \
116	-d '{"message": "Hello from another agent"}'
117	```
118
119	## A2A vs MCP
120
121	\| Feature \| A2A \| MCP \|
122	\|---------\|-----\|-----\|
123	\| Purpose \| Agent-to-agent chat delegation \| Tool/function access \|
124	\| Use Case \| Long-running conversations \| Specific tool calls \|
125	\| Context \| Full chat context \| Function parameters only \|
126	\| Best For \| Workflow delegation \| Tool integration \|
127
128	> [!TIP]
129	> Use A2A when you need another agent's reasoning and conversation capabilities. Use MCP when you just need access to specific tools or functions.
130
131	## Troubleshooting
132
133	### Connection Refused
134
135	- Verify the A2A server is enabled in Settings
136	- Check that the Agent Zero instance is running
137	- Confirm the port is accessible (check firewall rules)
138
139	### Invalid Token
140
141	- Token may have changed due to credential updates
142	- Generate a new connection URL from Settings > MCP/A2A
143	- Update the connecting agent's configuration
144
145	### Project Not Found
146
147	- Verify the project name in the URL matches exactly
148	- Check that the project exists in the target instance
149	- Project names are case-sensitive
150
151	## Advanced Configuration
152
153	For detailed A2A protocol specifications, API examples, and integration patterns, see the [Advanced Connectivity Guide](../developer/connectivity.md).