Connect an A2A agent
Once your A2A server agent is deployed and reachable, connect it to a Copilot in Agent Studio → A2A Agents. The Copilot then discovers your agent’s skills and delegates matching tasks to it automatically.
Before you begin
Section titled “Before you begin”- Your remote A2A server agent must run over HTTPS and be reachable.
- It must serve an Agent Card at
/.well-known/agent.json(or a custom URL). - You need the agent’s base URL and authentication credentials.
- A Copilot can connect up to 20 A2A agents.
Connection details
Section titled “Connection details”Path: Agent Studio → A2A Agents → Add Agent
| Field | Required | Description |
|---|---|---|
| Display Name | Yes | A friendly name for this agent (e.g. “Status Monitor Agent”). Shown in the Copilot’s tool list. |
| Base URL | Yes | The root URL where the remote A2A agent is hosted (e.g. https://my-agent.example.com). |
| Agent Card URL | No | Override the default card location. Leave blank to use <base-url>/.well-known/agent.json. |
| Protocol Version | Yes | Currently A2A v0.3 (auto-selected). |
Authentication
Section titled “Authentication”| Auth type | When to use | Fields |
|---|---|---|
| None | Agent is open or network-restricted (no auth headers sent) | — |
| Bearer Token | Agent expects Authorization: Bearer <token> | Token value |
| API Key | Agent expects X-API-Key: <key> | Key value |
After saving, click Fetch Agent Card to validate the connection and pull in your agent’s skills, then choose which skills to expose to the Copilot.
Advanced settings (optional)
Section titled “Advanced settings (optional)”Forward user context
Section titled “Forward user context”Toggle on to pass the current user’s identity to the remote agent via the X-Foldspace-User-Id header. You can also include a structured user-context data part:
| Source field | Default key | Description |
|---|---|---|
| User Email | user_email | The authenticated user’s email address |
| User ID | user_id | The user’s unique identifier |
| Subscription ID | subscription_id | The customer’s subscription identifier |
Additional headers
Section titled “Additional headers”Add static custom headers (for API versioning, routing, etc.) sent on every request to your agent.
Connection timeouts
Section titled “Connection timeouts”| Setting | Default | Range | Description |
|---|---|---|---|
| Connect Timeout | 10s | 1–300s | Max time to establish a connection |
| Request Timeout | 120s | 1–600s | Max time to wait for a single HTTP response |
| Task Timeout | 300s | 1–900s | Max total time for an A2A task to complete |
Troubleshooting
Section titled “Troubleshooting”| Problem | Solution |
|---|---|
| ”Failed to fetch agent card” | Verify the Base URL is reachable, the Agent Card URL serves valid JSON, and your auth credentials are correct. |
| Agent shows but the Copilot doesn’t invoke it | Check that the agent is Enabled and has at least one Exposed skill. |
| Authentication errors at runtime | Confirm the token or API key hasn’t expired or been revoked. |
| Agent times out during execution | Increase the Task Timeout in Advanced settings (default 300s). |
Related
Section titled “Related”- A2A server agents — concepts and the Agent Card.
- A2A quickstart — build your first agent.
- A2A advanced patterns — LangGraph, TypeScript, Java, native.
- A2A agents (Agent Studio) — the product overview.