How to Connect an A2A Agent in Foldspace
Register an external AI agent with your Foldspace Copilot so it can delegate tasks to it using the Agent-to-Agent (A2A) protocol. This guide walks you through adding, authenticating, and configuring a remote A2A agent from the Foldspace Agent Studio.
Before You Begin
- Your remote A2A server agent must be running and reachable over HTTPS.
- It must serve an Agent Card at
/.well-known/agent.json(or a custom URL you specify). - You need the agent's base URL and authentication credentials (if any).
- You can connect up to 20 A2A agents per Copilot.
Step 1: Open the A2A Agents Page
- Navigate to Agent Studio in Foldspace.
- Select the Copilot you want to connect the remote agent to.
- Open the A2A Agents tab.
You'll see a list of any previously configured A2A agents, or an empty state with an Add Agent button.
Step 2: Add a New Agent
- Click Add Agent.
- A configuration dialog opens with four sections:
- Connection Details
- Authentication
- Advanced Configuration
- Agent Card
Step 3: Fill In Connection Details
| 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 agent card location. Leave blank to use <base-url>/.well-known/agent.json. |
| Protocol Version | Yes | Currently set to A2A v0.3 (auto-selected). |
Step 4: Configure Authentication
Select the authentication method your remote agent requires:
| 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 |
Secrets are encrypted at rest. Once saved, they display as masked (••••••••). Click Replace to rotate a credential.
Step 5: Save the Configuration
Click Create Agent at the bottom of the dialog. The agent is now registered but has not yet fetched its capabilities.
After saving, the dialog switches to edit mode so you can immediately fetch the Agent Card.
Step 6: Fetch the Agent Card
- In the Agent Card section at the bottom of the dialog, click Fetch Agent Card.
- Foldspace connects to your agent's Agent Card URL, downloads the card, and displays:
- Agent name and version
- Description
- Provider (if specified in the card)
- Skills — the list of capabilities your agent advertises
If the fetch fails, check that the Base URL is correct and that authentication credentials are valid.
Step 7: Choose Which Skills to Expose
After fetching the Agent Card, you'll see the agent's skills listed with Exposed / Hidden toggles:
- By default, all skills are exposed to the Copilot.
- Click a skill to toggle it between Exposed and Hidden.
- At least one skill must remain exposed.
- Use Expose all to remove any custom filter.
Only exposed skills will be available as tools for the Copilot to invoke.
Step 8: Configure Advanced Settings (Optional)
Expand the Advanced Configuration accordion to access:
Forward User Context
Toggle Forward User Context to pass the current user's identity to the remote agent via the X-Foldspace-User-Id header.
User Context Data Part
Include user context fields directly in the A2A message body (as a structured 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 |
Toggle each field on/off and customize the key name the remote agent receives.
Additional Headers
Add custom HTTP headers sent with every request to this agent. Click + Add Header and enter a key/value pair.
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 |
Step 9: Enable or Disable the Agent
Back on the A2A Agents list, each agent has an Enabled toggle. When disabled, the Copilot will not invoke that agent — useful for maintenance windows or testing.
Managing Agents
From the A2A Agents list you can:
- Edit — Click a row or use the edit action to reopen the configuration dialog.
- Delete — Remove an agent permanently. A confirmation prompt warns that copilots relying on its skills may break.
- Search — Filter the list by display name or URL.
- Toggle — Enable/disable agents without deleting them.
Troubleshooting
-
Problem: "Failed to fetch agent card"
What to do: Verify the Base URL is reachable, the Agent Card URL serves valid JSON, and your auth credentials are correct. The fetch uses the saved configuration — if you changed fields, save first. -
Problem: Agent shows in the list but the Copilot doesn't invoke it.
What to do: Check that the agent is Enabled and has at least one Exposed skill. Also verify the agent's skill descriptions are clear enough for the Copilot to match user intent. -
Problem: Authentication errors at runtime.
What to do: Confirm the token or API key hasn't expired or been revoked. If you recently rotated credentials, make sure the new value is saved in the configuration. -
Problem: Agent times out during task execution.
What to do: Increase the Task Timeout in Advanced Configuration. The default is 300 seconds (5 minutes). Long-running agents may need up to 900 seconds (15 minutes).
Updated about 1 month ago