Agent Studio

A2A agents

Path: Agent Studio → A2A Agents

Configure Agent-to-Agent (A2A) connections, allowing your Foldspace agent to delegate tasks to or receive tasks from other AI agents.

Use A2A when the work belongs to a system that runs its own agent: your Foldspace agent hands off the task, the other agent does the work, and the result comes back into the conversation. For multi-step work that lives inside your own product, a Task Agent is usually the better fit.

What Is an A2A Server Agent?

An A2A server agent (also called a “remote agent”) is an AI-powered service that exposes its capabilities over HTTP using the A2A protocol. Any A2A-compatible client — including orchestrators, platforms like Foldspace, or other agents — can discover your agent via its Agent Card, send it tasks, and receive results through a standardized interface.

The protocol is built on JSON-RPC 2.0 over HTTP(S), supports Server-Sent Events (SSE) for streaming, and uses Agent Cards for capability discovery.

How Foldspace Uses A2A

In Foldspace, the Copilot agent acts as the A2A client. When a user interacts with a Copilot, it discovers your server agent via its Agent Card, delegates tasks to it, and presents results back to the user. Your job is to build the server side.

User → Foldspace Copilot (A2A client) → Your Server Agent (A2A server)
                                      ←  Task results / streaming updates

Your A2A server agent is invoked automatically when the Copilot determines your agent’s skills match the user’s intent. You only need to build and register the server side — Foldspace handles all client-side orchestration.

What Foldspace Supports

Capability	How It Works
Streaming	Real-time SSE updates. When your agent emits status or artifact events, users see progress live in the conversation.
Tool Progress	When your agent invokes tools during execution, Foldspace surfaces progress indicators to users automatically.
Authentication	Configure your Agent Card’s auth schemes (Bearer, OAuth 2.0, API key, mTLS) and Foldspace manages credential passing.
User Input (Multi-Turn)	Set task state to `input-required` and the Copilot prompts the user, then relays their response back to your agent.

Debugging A2A Calls

Every A2A invocation is recorded in Conversations. Open a conversation, click View Analysis on the agent message, and select the Actions tab: each A2A call appears with a Remote Agent badge, the action that triggered it, and its status. Expand a call to inspect the Arguments sent to your agent, the Response it returned, and the total execution time.

To narrow the list, open the Actions filter in Conversations and select your A2A agent by name — connected A2A agents appear in that dropdown alongside your actions, tagged with an A2A badge.

Key Concepts

Concept	Description
Agent Card	A JSON manifest describing your agent’s name, skills, endpoints, authentication, and capabilities. Hosted at `/.well-known/agent.json`.
Task	The unit of work. Has a lifecycle: `submitted` → `working` → `completed` / `failed` / `canceled`.
Message	Carries multimodal content (text, files, structured data) between client and server.
Artifact	The output/result of a completed task, streamed incrementally.
Streaming (SSE)	Real-time status updates and partial results over Server-Sent Events.

Agent Card Reference

The Agent Card is the entry point for all A2A interactions. It tells clients what your agent can do and how to reach it.

{
  "name": "Your Agent Name",
  "description": "What your agent does in one sentence",
  "url": "https://your-agent.example.com/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "default_input_modes": ["text/plain"],
  "default_output_modes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "skill-identifier",
      "name": "Human-Readable Skill Name",
      "description": "What this skill does",
      "tags": ["relevant", "tags"],
      "examples": ["Example input that triggers this skill"]
    }
  ],
  "authentication": {
    "schemes": ["bearer"]
  }
}

Required fields: name, url, version, capabilities, skills

Implementation Approaches

There are three ways to build an A2A server agent:

Approach	Best for	Languages
Official SDK	Most developers — handles protocol compliance automatically	Python, TypeScript, Java
LangGraph + SDK	Teams already using LangGraph for agent orchestration	Python
Native (no SDK)	Full control, unsupported languages, or minimal dependencies	Any language with HTTP support