# Connect an A2A agent

Register your A2A server agent in Foldspace Agent Studio — connection details, authentication, user-context forwarding, and timeouts.

Once your [A2A server agent](/guides/a2a-server-agents/) 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

- 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.

## The agent list

**Agent Studio → A2A Agents** lists every agent connected to this Copilot:

| Column | What it shows |
| :--- | :--- |
| **Name** | The display name you gave the agent. This is also how it appears in the **Actions** filter in [Conversations](/user-guides/conversations/). |
| **Base URL** | The root URL of the remote agent. |
| **Auth** | The auth type in use — **None**, **Bearer Token**, or **API Key**. |
| **Agent Card** | The name from the fetched Agent Card and its skill count. A green check means the card was fetched and validated. |
| **Status** | Toggle an agent on or off. A disabled agent stays configured, but the Copilot won't invoke it. |

Use **Add Agent** to connect a new one, or the **⋯** menu on a row for per-agent options.

## 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

| 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   |

:::note
Secrets are encrypted at rest. Once saved, they display masked (`••••••••`). Click **Replace** to rotate a credential.
:::

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)

### 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

Add static custom headers (for API versioning, routing, etc.) sent on every request to your agent.

### 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

Start in Agent Studio → **Conversations** and open the **Actions** filter — your A2A agent is listed there by its display name. Select it and click **Apply** to narrow the list to conversations that delegated to it. Open one, click **View Analysis** on the agent message, and check the **Actions** tab: each A2A call shows a **Remote Agent** badge, its status, and — when expanded — the **Arguments** sent, the **Response** returned, and the execution time. That's usually enough to tell a timeout apart from an auth failure or a bad payload.

| 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

- [A2A server agents](/guides/a2a-server-agents/) — concepts and the Agent Card.
- [A2A quickstart](/guides/a2a-quickstart/) — build your first agent.
- [A2A advanced patterns](/guides/a2a-advanced/) — LangGraph, TypeScript, Java, native.
- [A2A agents (Agent Studio)](/user-guides/a2a-agents/) — the product overview.