# A2A server agents

Build an Agent-to-Agent (A2A) server agent that the Foldspace Copilot can discover, delegate tasks to, and stream results from — with Python, TypeScript, Java, and LangGraph examples.

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](/user-guides/a2a-agents/).

## 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](https://a2a-protocol.org). 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.

```text
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, 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

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

:::note
The text you send via `add_artifact(...)` is what the Foldspace Copilot shows as the **answer**. Status updates (`update_status(state="working", ...)`) are treated as **progress** only.
:::

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

```json title="/.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

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](https://www.langchain.com/langgraph) + SDK** | Teams already using [LangGraph](https://langchain-ai.github.io/langgraph/) for agent orchestration | Python |
| **Native (no SDK)**                                       | Full control, unsupported languages, or minimal dependencies | Any language with HTTP support |

Already orchestrating agents with [LangGraph](https://github.com/langchain-ai/langgraph)? You can expose an existing LangGraph graph as an A2A server agent with a thin executor bridge — see [Advanced patterns](/guides/a2a-advanced/#langgraph-integration).

## Next steps

- **[Quickstart →](/guides/a2a-quickstart/)** — build and test your first A2A server agent in Python.
- **[Advanced patterns →](/guides/a2a-advanced/)** — LangGraph, TypeScript, Java, native (no-SDK), and streaming.
- **[Connect to Foldspace →](/guides/a2a-connect/)** — register your agent in Agent Studio.