a2a 0.1.0 → 0.2.0

data/.agent-docs/topics/key-concepts.md

@@ -0,0 +1,99 @@
+# Core Concepts and Components in A2A
+
+A2A uses a set of core concepts that define how agents interact.
+Understand these core building blocks to develop or integrate with A2A-compliant
+systems.
+
+![A2A Actors showing a User, A2A Client (Client Agent), and A2A Server (Remote Agent)](../assets/a2a-actors.png){ width="70%" style="margin:20px auto;display:block;" }
+
+## Core Actors in A2A Interactions
+
+- **User**: The end user, which can be a human operator or an automated
+    service. The user initiates a request or defines a goal that requires
+    assistance from one or more AI agents.
+- **A2A Client (Client Agent)**: An application, service, or another AI agent
+    that acts on behalf of the user. The client initiates communication using the
+    A2A protocol.
+- **A2A Server (Remote Agent)**: An AI agent or an agentic system that exposes
+    an HTTP endpoint implementing the A2A protocol. It receives requests from
+    clients, processes tasks, and returns results or status updates. From the client's perspective,
+    the remote agent operates as an _opaque_ (black-box) system, meaning its internal workings, memory, or tools are not exposed.
+
+## Fundamental Communication Elements
+
+The following table describes the fundamental communication elements in A2A:
+
+| Element | Description | Key Purpose |
+| :------ | :---------- | :---------- |
+| Agent Card | A JSON metadata document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
+| Task | A stateful unit of work initiated by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and enables multi-turn interactions and collaboration. |
+| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, context, questions, answers, or status updates that are not necessarily formal artifacts. |
+| Part | The fundamental content container (for example, TextPart, FilePart, DataPart) used within Messages and Artifacts. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
+| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Delivers the concrete results of an agent's work, ensuring structured and retrievable outputs. |
+
+## Interaction Mechanisms
+
+The A2A Protocol supports various interaction patterns to accommodate different
+needs for responsiveness and persistence. These mechanisms ensure that agents
+can exchange information efficiently and reliably, regardless of the task's
+complexity or duration:
+
+- **Request/Response (Polling)**: Clients send a request and the server
+    responds. For long-running tasks, the client periodically polls the server
+    for updates.
+- **Streaming with Server-Sent Events (SSE)**: Clients initiate a stream to
+    receive real-time, incremental results or status updates from the server
+    over an open HTTP connection.
+- **Push Notifications**: For very long-running tasks or disconnected
+    scenarios, the server can actively send asynchronous notifications to a
+    client-provided webhook when significant task updates occur.
+
+For a detailed exploration of streaming and push notifications, refer to the
+[Streaming & Asynchronous Operations](./streaming-and-async.md) document.
+
+## Agent Cards
+
+The Agent Card is a JSON document that serves as a digital business card for
+initial discovery and interaction setup. It provides essential metadata about an
+agent. Clients parse this information to determine if an agent is suitable for a
+given task, how to structure requests, and how to communicate securely. Key
+information includes identity, service endpoint (URL), A2A capabilities,
+authentication requirements, and a list of skills.
+
+## Messages and Parts
+
+A message represents a single turn of communication between a client and an
+agent. It includes a role ("user" or "agent") and a unique `messageId`. It
+contains one or more Part objects, which are granular containers for the actual
+content. This design allows A2A to be modality independent.
+
+The primary part kinds are:
+
+- `TextPart`: Contains plain textual content.
+- `FilePart`: Represents a file. It can be transmitted either inline (Base64
+   encoded) or through a URI. It includes metadata like "filename" and "mimeType".
+- `DataPart`: Carries structured JSON data. This is useful for forms,
+   parameters, or any machine-readable information.
+
+## Artifacts
+
+An artifact represents a tangible output or a concrete result generated by a
+remote agent during task processing. Unlike general messages, artifacts are the
+actual deliverables. An artifact has a unique `artifactId`, a human-readable
+name, and consists of one or more part objects. Artifacts are closely tied to the
+task lifecycle and can be streamed incrementally to the client.
+
+## Agent Response: Task or Message
+
+The agent response can be a new `Task` (when the agent needs to perform a
+long-running operation) or a `Message` (when the agent can respond immediately).
+
+For more details, see [Life of a Task](./life-of-a-task.md).
+
+## Other Important Concepts
+
+- **Context (`contextId`):** A server-generated identifier that can be used to logically group multiple related `Task` objects, providing context across a series of interactions.
+- **Transport and Format:** A2A communication occurs over HTTP(S). JSON-RPC 2.0 is used as the payload format for all requests and responses.
+- **Authentication & Authorization:** A2A relies on standard web security practices. Authentication requirements are declared in the Agent Card, and credentials (e.g., OAuth tokens, API keys) are typically passed through HTTP headers, separate from the A2A protocol messages themselves. For more information, see [Enterprise-Ready Features](./enterprise-ready.md).
+- **Agent Discovery:** The process by which clients find Agent Cards to learn about available A2A Servers and their capabilities. For more information, see [Agent Discovery](./agent-discovery.md).
+- **Extensions:** A2A allows agents to declare custom protocol extensions as part of their AgentCard. For more information, see [Extensions](./extensions.md).

data/.agent-docs/topics/life-of-a-task.md

@@ -0,0 +1,255 @@
+# Life of a Task
+
+In the Agent2Agent (A2A) Protocol, interactions can range from simple, stateless
+exchanges to complex, long-running processes. When an agent receives a message
+from a client, it can respond in one of two fundamental ways:
+
+- **Respond with a Stateless `Message`**: This type of response is
+    typically used for immediate, self-contained interactions that conclude
+    without requiring further state management.
+- **Initiate a Stateful `Task`**: If the response is a `Task`, the agent will
+    process it through a defined lifecycle, communicating progress and requiring
+    input as needed, until it reaches an interrupted state (e.g.,
+    `input-required`, `auth-required`) or a terminal state (e.g., `completed`,
+    `canceled`, `rejected`, `failed`).
+
+## Group Related Interactions
+
+A `contextId` is a crucial identifier that logically groups multiple `Task`
+objects and independent `Message` objects, providing continuity across a series of
+interactions.
+
+- When a client sends a message for the first time, the agent responds
+    with a new `contextId`. If a task is initiated, it will also have a `taskId`.
+- Clients can send subsequent messages and include the same `contextId` to
+    indicate that they are continuing their previous interaction within the same
+    context.
+- Clients optionally attach the `taskId` to a subsequent message to
+    indicate that it continues that specific task.
+
+The `contextId` enables collaboration towards a common goal or a shared
+contextual session across multiple, potentially concurrent tasks. Internally, an
+A2A agent (especially one using an LLM) uses the `contextId` to manage its internal
+conversational state or its LLM context.
+
+## Agent Response: Message or Task
+
+The choice between responding with a `Message` or a `Task` depends on the
+nature of the interaction and the agent's capabilities:
+
+- **Messages for Trivial Interactions**: `Message` objects are suitable for
+    transactional interactions that don't require long-running
+    processing or complex state management. An agent might use messages to
+    negotiate the acceptance or scope of a task before committing to a `Task`
+    object.
+- **Tasks for Stateful Interactions**: Once an agent maps the intent of an
+    incoming message to a supported capability that requires substantial,
+    trackable work over an extended period, the agent responds with a `Task`
+    object.
+
+Conceptually, agents operate at different levels of complexity:
+
+- **Message-only Agents**: Always respond with `Message` objects. They
+    typically don't manage complex state or long-running executions, and use
+    `contextId` to tie messages together. These agents might directly wrap LLM
+    invocations and simple tools.
+- **Task-generating Agents**: Always respond with `Task` objects, even for
+    responses, which are then modeled as completed tasks. Once a task is
+    created, the agent will only return `Task` objects in response to messages
+    sent, and once a task is complete, no more messages can be sent. This
+    approach avoids deciding between `Task` versus `Message`, but creates completed task objects
+    for even simple interactions.
+- **Hybrid Agents**: Generate both `Message` and `Task` objects. These agents
+    use messages to negotiate agent capability and the scope of work for a task,
+    then send a `Task` object to track execution and manage states like
+    `input-required` or error handling. Once a task is created, the agent will
+    only return `Task` objects in response to messages sent, and once a task is
+    complete, no more messages can be sent. A hybrid agent uses messages to
+    negotiate the scope of a task, and then generate a task to track its
+    execution.
+    For more information about hybrid agents, see [A2A protocol: Demystifying Tasks vs Messages](https://discuss.google.dev/t/a2a-protocol-demystifying-tasks-vs-messages/255879).
+
+## Task Refinements
+
+Clients often need to send new requests based on task results or refine the
+outputs of previous tasks. This is modeled by starting another interaction using
+the same `contextId` as the original task. Clients further hint the agent by
+providing references to the original task using `referenceTaskIds` in the
+`Message` object. The agent then responds with either a new `Task` or a
+`Message`.
+
+## Task Immutability
+
+Once a task reaches a terminal state (completed, canceled, rejected, or failed),
+it cannot restart. Any subsequent interaction related to that task, such as a
+refinement, must initiate a new task within the same `contextId`. This principle
+offers several benefits:
+
+- **Task Immutability.** Clients reliably reference tasks and their
+    associated state, artifacts, and messages, providing a clean mapping of
+    inputs to outputs. This is valuable for orchestration and traceability.
+- **Clear Unit of Work.** Every new request, refinement, or follow-up becomes
+    a distinct task. This simplifies bookkeeping, allows for granular tracking
+    of an agent's work, and enables tracing each artifact to a specific unit of
+    work.
+- **Easier Implementation.** This removes ambiguity for agent developers
+    regarding whether to create a new task or restart an existing one.
+
+## Parallel Follow-ups
+
+A2A supports parallel work by enabling agents to create distinct, parallel
+tasks for each follow-up message sent within the same `contextId`. This allows
+clients to track individual tasks and create new dependent tasks as soon as a
+prerequisite task is complete.
+
+For example:
+
+- Task 1: Book a flight to Helsinki.
+- Task 2: Based on Task 1, book a hotel.
+- Task 3: Based on Task 1, book a snowmobile activity.
+- Task 4: Based on Task 2, add a spa reservation to the hotel booking.
+
+## Referencing Previous Artifacts
+
+The serving agent infers the relevant artifact from a referenced task or from the
+`contextId`. As the domain expert, the serving agent is best suited to resolve
+ambiguity or identify missing information. If there is ambiguity, the agent asks
+the client for clarification by returning an `input-required` state. The client
+then specifies the artifact in its response, optionally populating artifact
+references (`artifactId`, `taskId`) in `Part` metadata.
+
+## Tracking Artifact Mutation
+
+Follow-up or refinement tasks often lead to the creation of new artifacts based on older ones. Tracking these mutations is important to ensure that only the most recent version of an artifact is used in subsequent interactions. This could be conceptualized as a version history, where each new artifact is linked to its predecessor.
+
+However, the client is in the best position to manage this artifact linkage. The client determines what constitutes an acceptable result and has the ability to accept or reject new versions. Therefore, the serving agent shouldn't be responsible for tracking artifact mutations, and this linkage is not part of the A2A protocol specification. Clients should maintain this version history on their end and present the latest acceptable version to the user.
+
+To facilitate client-side tracking, serving agents should use a consistent `artifact-name` when generating a refined version of an existing artifact.
+
+When initiating follow-up or refinement tasks, the client should explicitly reference the specific artifact they intend to refine, ideally the "latest" version from their perspective. If the artifact reference is not provided, the serving agent can:
+
+- Attempt to infer the intended artifact based on the current `contextId`.
+- If there is ambiguity or insufficient context, the agent should respond with an `input-required` task state to request clarification from the client.
+
+## Example Follow-up Scenario
+
+The following example illustrates a typical task flow with a follow-up:
+
+1. Client sends a message to the agent:
+
+    ```json
+    {
+      "jsonrpc": "2.0",
+      "id": "req-001",
+      "method": "message.send",
+      "params": {
+        "message": {
+          "role": "user",
+          "parts": [
+            {
+              "kind": "text",
+              "text": "Generate an image of a sailboat on the ocean."
+            }
+          ]
+          "messageId": "msg-user-001"
+        }
+      }
+    }
+    ```
+
+2. Agent responds with a boat image (completed task):
+
+    ```json
+    {
+      "jsonrpc": "2.0",
+      "id": "req-001",
+      "result": {
+        "id": "task-boat-gen-123",
+        "contextId": "ctx-conversation-abc",
+        "status": {
+          "state": "completed"
+        },
+        "artifacts": [
+          {
+            "artifactId": "artifact-boat-v1-xyz",
+            "name": "sailboat_image.png",
+            "description": "A generated image of a sailboat on the ocean.",
+            "parts": [
+              {
+                "kind": "file",
+                "file": {
+                  "name": "sailboat_image.png",
+                  "mimeType": "image/png",
+                  "bytes": "base64_encoded_png_data_of_a_sailboat"
+                }
+              }
+            ]
+          }
+        ],
+        "kind": "task"
+      }
+    }
+    ```
+
+3. Client asks to color the boat red. This refinement request refers to the
+    previous `taskId` and uses the same `contextId`.
+
+    ```json
+    {
+      "jsonrpc": "2.0",
+      "id": "req-002",
+      "method": "message.send",
+      "params": {
+        "message": {
+          "role": "user",
+          "messageId": "msg-user-002",
+          "contextId": "ctx-conversation-abc",
+          "referenceTaskIds": [
+            "task-boat-gen-123"
+          ],
+          "parts": [
+            {
+              "kind": "text",
+              "text": "Please modify the sailboat to be red."
+            }
+          ]
+        }
+      }
+    }
+    ```
+
+4. Agent responds with a new image artifact (new task, same context, updated
+    artifact name): The agent creates a new task within the same `contextId`. The
+    new boat image artifact retains the same name but has a new `artifactId`.
+
+    ```json
+    {
+      "jsonrpc": "2.0",
+      "id": "req-002",
+      "result": {
+        "id": "task-boat-color-456",
+        "contextId": "ctx-conversation-abc",
+        "status": {
+          "state": "completed"
+        },
+        "artifacts": [
+          {
+            "artifactId": "artifact-boat-v2-red-pqr",
+            "name": "sailboat_image.png",
+            "description": "A generated image of a red sailboat on the ocean.",
+            "parts": [
+              {
+                "kind": "file",
+                "file": {
+                  "name": "sailboat_image.png",
+                  "mimeType": "image/png",
+                  "bytes": "base64_encoded_png_data_of_a_RED_sailboat"
+                }
+              }
+            ]
+          }
+        ],
+        "kind": "task"
+      }
+    }
+    ```

data/.agent-docs/topics/streaming-and-async.md

@@ -0,0 +1,111 @@
+# Streaming and Asynchronous Operations for Long-Running Tasks
+
+The Agent2Agent (A2A) protocol is explicitly designed to handle tasks that might not complete immediately. Many AI-driven operations are often long-running, involve multiple steps, produce incremental results, or require human intervention. A2A provides mechanisms for managing such asynchronous interactions, ensuring that clients receive updates effectively, whether they remain continuously connected or operate in a more disconnected fashion.
+
+## Streaming with Server-Sent Events (SSE)
+
+For tasks that produce incremental results (like generating a long document or streaming media) or provide ongoing status updates, A2A supports real-time communication using Server-Sent Events (SSE). This approach is ideal when the client is able to maintain an active HTTP connection with the A2A Server.
+
+The following key features detail how SSE streaming is implemented and managed within the A2A protocol:
+
+- **Server Capability:** The A2A Server must indicate its support for streaming by setting `capabilities.streaming: true` in its Agent Card.
+
+- **Initiating a Stream:** The client uses the `message/stream` RPC method to send an initial message (for example, a prompt or command) and simultaneously subscribe to updates for that task.
+
+- **Server Response and Connection:** If the subscription is successful, the server responds with an HTTP 200 OK status and a `Content-Type: text/event-stream`. This HTTP connection remains open for the server to push events to the client.
+
+- **Event Structure and Types:** The server sends events over this stream. Each event's `data` field contains a JSON-RPC 2.0 Response object, typically a `SendStreamingMessageResponse`. The `result` field of the `SendStreamingMessageResponse` contains:
+
+    - [`Task`](../specification.md#61-task-object): Represents the current state of the work.
+    - [`TaskStatusUpdateEvent`](../specification.md#722-taskstatusupdateevent-object): Communicates changes in the task's lifecycle state (for example, from `working` to `input-required` or `completed`). It also provides intermediate messages from the agent.
+    - [`TaskArtifactUpdateEvent`](../specification.md#723-taskartifactupdateevent-object): Delivers new or updated Artifacts generated by the task. This is used to stream large files or data structures in chunks, with fields like `append` and `lastChunk` to help reassemble.
+
+- **Stream Termination:** The server signals the end of updates for a cycle by setting `final: true` in a `TaskStatusUpdateEvent`. This typically occurs when the task reaches a terminal state. After this, the server usually closes the SSE connection.
+
+- **Resubscription:** If a client's SSE connection breaks prematurely while a task is still active, the client is able to attempt to reconnect to the stream using the `tasks/resubscribe` RPC method.
+
+### When to Use Streaming
+
+Streaming with SSE is best suited for:
+
+- Real-time progress monitoring of long-running tasks.
+- Receiving large results (artifacts) incrementally.
+- Interactive, conversational exchanges where immediate feedback or partial responses are beneficial.
+- Applications requiring low-latency updates from the agent.
+
+### Protocol Specification References
+
+Refer to the Protocol Specification for detailed structures:
+
+- [`message/stream`](../specification.md#72-messagestream)
+- [`tasks/resubscribe`](../specification.md#79-tasksresubscribe)
+
+## Push Notifications for Disconnected Scenarios
+
+For very long-running tasks (for example, lasting minutes, hours, or even days) or when clients are unable to or prefer not to maintain persistent connections (like mobile clients or serverless functions), A2A supports asynchronous updates using push notifications. This allows the A2A Server to actively notify a client-provided webhook when a significant task update occurs.
+
+The following key features detail how push notifications are implemented and managed within the A2A protocol:
+
+- **Server Capability:** The A2A Server must indicate its support for this feature by setting `capabilities.pushNotifications: true` in its Agent Card.
+- **Configuration:** The client provides a [`PushNotificationConfig`](../specification.md#68-pushnotificationconfig-object) to the server. This configuration is supplied:
+    - Within the initial `message/send` or `message/stream` request, or
+    - Separately, using the `tasks/pushNotificationConfig/set` RPC method for an existing task.
+    The `PushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
+- **Notification Trigger:** The A2A Server decides when to send a push notification, typically when a task reaches a significant state change (for example, terminal state, `input-required`, or `auth-required`).
+- **Notification Payload:** The A2A protocol does not strictly define the HTTP body payload, but it SHOULD contain sufficient information for the client to identify the Task ID and understand the general nature of the update (for example, the new `TaskState`).
+- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `tasks/get` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
+
+### When to Use Push Notifications
+
+Push notifications are ideal for:
+
+- Very long-running tasks that can take minutes, hours, or days to complete.
+- Clients that cannot or prefer not to maintain persistent connections, such as mobile applications or serverless functions.
+- Scenarios where clients only need to be notified of significant state changes rather than continuous updates.
+
+### Protocol Specification References
+
+Refer to the Protocol Specification for detailed structures:
+
+- [`tasks/pushNotificationConfig/set`](../specification.md#75-taskspushnotificationconfigset)
+- [`tasks/get`](../specification.md#76-taskspushnotificationconfigget)
+
+### Client-Side Push Notification Service
+
+The `url` specified in `PushNotificationConfig.url` points to a client-side Push Notification Service. This service is responsible for receiving the HTTP POST notification from the A2A Server. Its responsibilities include authenticating the incoming notification, validating its relevance, and relaying the notification or its content to the appropriate client application logic or system.
+
+### Security Considerations for Push Notifications
+
+Security is paramount for push notifications due to their asynchronous and server-initiated outbound nature. Both the A2A Server (sending the notification) and the client's webhook receiver have critical responsibilities.
+
+#### A2A Server Security (when sending notifications to client webhook)
+
+- **Webhook URL Validation:** Servers SHOULD NOT blindly trust and send POST requests to any URL provided by a client. Malicious clients could provide URLs pointing to internal services or unrelated third-party systems, leading to Server-Side Request Forgery (SSRF) attacks or acting as Distributed Denial of Service (DDoS) amplifiers.
+    - **Mitigation strategies:** Allowlisting of trusted domains, ownership verification (for example, challenge-response mechanisms), and network controls (e.g., egress firewalls).
+- **Authenticating to the Client's Webhook:** The A2A Server MUST authenticate itself to the client's webhook URL according to the scheme(s) specified in `PushNotificationConfig.authentication`. Common schemes include Bearer Tokens (OAuth 2.0), API keys, HMAC signatures, or mutual TLS (mTLS).
+
+#### Client Webhook Receiver Security (when receiving notifications from A2A server)
+
+- **Authenticating the A2A Server:** The webhook endpoint MUST rigorously verify the authenticity of incoming notification requests to ensure they originate from the legitimate A2A Server and not an imposter.
+    - **Verification methods:** Verify signatures/tokens (for example, JWT signatures against the A2A Server's trusted public keys, HMAC signatures, or API key validation). Also, validate the `PushNotificationConfig.token` if provided.
+- **Preventing Replay Attacks:**
+    - **Timestamps:** Notifications SHOULD include a timestamp. The webhook SHOULD reject notifications that are too old.
+    - **Nonces/unique IDs:** For critical notifications, consider using unique, single-use identifiers (for example, JWT's `jti` claim or event IDs) to prevent processing duplicate notifications.
+- **Secure Key Management and Rotation:** Implement secure key management practices, including regular key rotation, especially for cryptographic keys. Protocols like JWKS (JSON Web Key Set) facilitate key rotation for asymmetric keys.
+
+#### Example Asymmetric Key Flow (JWT + JWKS)
+
+1. Client sets `PushNotificationConfig` specifying `authentication.schemes: ["Bearer"]` and possibly an expected `issuer` or `audience` for the JWT.
+2. A2A Server, when sending a notification:
+    - Generates a JWT, signing it with its private key. The JWT includes claims like `iss` (issuer), `aud` (audience), `iat` (issued at), `exp` (expires), `jti` (JWT ID), and `taskId`.
+    - The JWT header indicates the signing algorithm and key ID (`kid`).
+    - The A2A Server makes its public keys available through a JWKS endpoint.
+3. Client Webhook, upon receiving the notification:
+    - Extracts the JWT from the Authorization header.
+    - Inspects the `kid` (key ID) in the JWT header.
+    - Fetches the corresponding public key from the A2A Server's JWKS endpoint (caching keys is recommended).
+    - Verifies the JWT signature using the public key.
+    - Validates claims (`iss`, `aud`, `iat`, `exp`, `jti`).
+    - Checks the `PushNotificationConfig.token` if provided.
+
+This comprehensive, layered approach to security for push notifications helps ensure that messages are authentic, integral, and timely, protecting both the sending A2A Server and the receiving client webhook infrastructure.