Skip to content
Foldspace Docs

A2A server agents

Open in ChatGPT Open in Claude

Agent-to-Agent (A2A) lets your Foldspace Copilot delegate work to an external AI agent — your A2A server agent — over a standard protocol, then stream the result back into the conversation.

This is the developer guide for building an A2A server agent. For the product / no-code side of connecting one in Agent Studio, see the A2A agents user guide.

What is an A2A server agent?

Section titled “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

Section titled “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

Section titled “What Foldspace supports”
CapabilityHow it works
StreamingReal-time SSE updates. When your agent emits status or artifact events, users see progress live in the conversation.
Tool progressWhen your agent invokes tools during execution, Foldspace surfaces progress indicators to users automatically.
AuthenticationConfigure your Agent Card’s auth schemes (Bearer, API key) 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

Section titled “Key concepts”
ConceptDescription
Agent CardA JSON manifest describing your agent’s name, skills, endpoints, authentication, and capabilities. Hosted at /.well-known/agent.json.
TaskThe unit of work. Has a lifecycle: submitted → working → completed / failed / canceled.
MessageCarries multimodal content (text, files, structured data) between client and server.
ArtifactThe output/result of a completed task, streamed incrementally.
Streaming (SSE)Real-time status updates and partial results over Server-Sent Events.

Agent Card reference

Section titled “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, and is served at /.well-known/agent.json.

/.well-known/agent.json
{
  "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

Section titled “Implementation approaches”

There are three ways to build an A2A server agent:

ApproachBest forLanguages
Official SDKMost developers — handles protocol compliance automaticallyPython, TypeScript, Java
LangGraph + SDKTeams already using LangGraph for agent orchestrationPython
Native (no SDK)Full control, unsupported languages, or minimal dependenciesAny language with HTTP support

Already orchestrating agents with LangGraph? You can expose an existing LangGraph graph as an A2A server agent with a thin executor bridge — see Advanced patterns.

Next steps

Section titled “Next steps”