From eeed69640117fa2c3e81fe60f79c11c2792e228e Mon Sep 17 00:00:00 2001 From: ningkegithub Date: Fri, 13 Jun 2025 13:46:44 +0800 Subject: [PATCH] docs: add architecture overview --- docs/architecture.md | 37 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 38 insertions(+) create mode 100644 docs/architecture.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..416acfa0e --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,37 @@ +# A2A Architecture Overview + +A2A (Agent2Agent) is an open protocol that lets independent agents collaborate over standard HTTP(S) and JSON-RPC 2.0. It provides a common language for discovering agents, exchanging messages, and coordinating long running tasks. + +![A2A architecture diagram](assets/a2a-main.png){width="60%" style="margin:20px auto;display:block;"} + +## Protocol Goals + +- **Interoperability:** allow agents built with different frameworks to work together. +- **Task management:** provide a shared model for initiating tasks, tracking state, and exchanging artifacts. +- **Flexible transports:** support simple request/response, real‑time streaming, and asynchronous push notifications. +- **Security:** rely on existing web standards for HTTPS and authentication while keeping agents opaque. + +## Core Concepts + +- **A2A Client** and **A2A Server** form the basic communication pair. The client sends JSON‑RPC requests to the server's HTTP endpoint. +- **Agent Card:** a metadata document describing an agent’s endpoint, capabilities, supported authentication schemes, and available skills. +- **Task:** the stateful unit of work tracked by the server. A task progresses through lifecycle states such as `submitted`, `working`, `input-required`, and `completed`. +- **Artifact:** files or structured data that an agent produces as part of a task. + +## Typical Task Flow + +1. The client retrieves the server’s Agent Card from a well‑known URL and learns its capabilities and required authentication. +2. The client authenticates and sends a `message/send` or `message/stream` request to start a task. +3. The server returns a `Task` object containing a unique `taskId` and current status. +4. As work progresses the client receives updates either through Server‑Sent Events, push notifications, or by polling `tasks/get`. +5. When the task reaches a terminal state (`completed`, `failed`, or `canceled`), the final artifacts and status are returned. + +## Streaming and Asynchronous Interaction + +- **Server-Sent Events (SSE):** When the server has `capabilities.streaming: true`, clients can call `message/stream` to keep an HTTP connection open and receive incremental `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` objects. The specification describes this in the [Streaming Transport](./specification.md#33-streaming-transport-server-sent-events) section. +- **Push notifications:** Servers that support `capabilities.pushNotifications` can send updates to a client’s webhook using the `tasks/pushNotificationConfig/*` methods. +- **Resubscribe:** If a connection drops, the client may resume streaming updates using `tasks/resubscribe`. + +## Authentication + +A2A uses standard HTTP authentication headers, discovered via the server’s Agent Card. Clients obtain credentials out‑of‑band and include them with every request (e.g., `Authorization: Bearer `). Servers must authenticate each request and MAY challenge with `401 Unauthorized` or `403 Forbidden` as noted in the [Authentication and Authorization](./specification.md#4-authentication-and-authorization) section. diff --git a/mkdocs.yml b/mkdocs.yml index 3efe471e2..4aed0a378 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,7 @@ extra: # Navigation nav: - Home: index.md + - Architecture: architecture.md - Topics: - What is A2A?: topics/what-is-a2a.md - Key Concepts: topics/key-concepts.md