A2A - Connect your agent to Fodlspace

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.

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