### Install protoc-gen-jsonschema Plugin

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install the `protoc-gen-jsonschema` plugin using Go. Ensure Go is installed first.

```bash
# Install via Go (requires Go to be installed first):
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest
```

--------------------------------

### Install protoc-gen-jsonschema Plugin on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install the `protoc-gen-jsonschema` plugin using Go on Windows. Ensure Go is installed first.

```powershell
# Install via Go (requires Go to be installed first):
go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest

# Verify installation (should be in your Go bin directory):
protoc-gen-jsonschema --version
```

--------------------------------

### Install Python Documentation Dependencies

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Set up a Python virtual environment and install the required documentation dependencies using pip.

```bash
# Create and activate virtual environment:
python3 -m venv .venv-docs
source .venv-docs/bin/activate

# Install requirements:
pip install -r requirements-docs.txt
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/a2aproject/a2a/blob/main/CONTRIBUTING.md

Installs all required Python packages for documentation development using uv.

```bash
uv pip install -r requirements-docs.txt
```

--------------------------------

### Installation

Source: https://github.com/a2aproject/a2a/blob/main/docs/sdk/python/index.md

Instructions on how to install the a2a-sdk Python package.

```APIDOC
## Installation

### Description
Install the `a2a-sdk` Python package using pip.

### Method
`pip`

### Endpoint
N/A

### Parameters
N/A

### Request Example
```sh
pip install a2a-sdk
```

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Install jq on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install the `jq` JSON processor on Windows, recommended via WinGet.

```powershell
# Install via WinGet:
winget install jqlang.jq

# Verify installation:
jq --version
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/a2aproject/a2a/blob/main/docs/README.md

Installs the necessary Python packages for building the documentation. Ensure you are in the correct directory before running.

```bash
pip install -r requirements-docs.txt
```

--------------------------------

### Uvicorn Server Output

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/5-start-server.md

This is an example of the console output you should see when the Uvicorn server starts successfully.

```console
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:9999 (Press CTRL+C to quit)
```

--------------------------------

### Install Core Build Tools on Debian/Ubuntu

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install essential build tools including `protoc`, `go`, and `jq` using apt-get on Debian/Ubuntu systems.

```bash
sudo apt-get update && sudo apt-get install -y protobuf-compiler golang jq
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/a2aproject/a2a/blob/main/CONTRIBUTING.md

Starts a local development server for the documentation with live reloading capabilities.

```bash
mkdocs serve
```

--------------------------------

### Install Python Documentation Dependencies on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Set up a Python virtual environment and install the required documentation dependencies using pip on Windows.

```powershell
# Create and activate virtual environment:
python -m venv .venv-docs
.\.venv-docs\Scripts\Activate.ps1

# Install requirements:
pip install -r requirements-docs.txt
```

--------------------------------

### Initialize and Start Helloworld Server

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/5-start-server.md

This code initializes the A2A server components, including the request handler and routes, and then starts the server using Uvicorn. It requires the AgentExecutor, TaskStore, and AgentCard objects.

```python
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse

from a2a.agent.executor import AgentExecutor
from a2a.agent.card import AgentCard
from a2a.task.store import TaskStore
from a2a.server.request_handler import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes

import uvicorn

# Assume HelloWorldAgentExecutor, InMemoryTaskStore, public_agent_card, and extended_agent_card are defined elsewhere

class HelloWorldAgentExecutor(AgentExecutor):
    async def execute(self, task_id: str, args: dict) -> dict:
        print(f"Executing task {task_id} with args: {args}")
        return {"message": "Hello, World!"}

class InMemoryTaskStore(TaskStore):
    def __init__(self):
        self._tasks = {}

    async def create_task(self, task_id: str, agent_id: str, method: str, args: dict, status: str = "pending") -> None:
        self._tasks[task_id] = {"agent_id": agent_id, "method": method, "args": args, "status": status}

    async def get_task(self, task_id: str) -> dict:
        return self._tasks.get(task_id)

    async def update_task_status(self, task_id: str, status: str) -> None:
        if task_id in self._tasks:
            self._tasks[task_id]["status"] = status

    async def delete_task(self, task_id: str) -> None:
        if task_id in self._tasks:
            del self._tasks[task_id]

# Placeholder for AgentCard objects
public_agent_card = AgentCard(
    agent_id="helloworld-agent",
    name="Helloworld Agent",
    description="A simple agent that says hello.",
    version="1.0",
    supported_interfaces=[
        {
            "type": "JSONRPC",
            "uri": "http://127.0.0.1:9999/",
            "protocol_version": "2.0"
        }
    ]
)

extended_agent_card = AgentCard(
    agent_id="helloworld-agent",
    name="Helloworld Agent",
    description="A simple agent that says hello.",
    version="1.0",
    supported_interfaces=[
        {
            "type": "JSONRPC",
            "uri": "http://127.0.0.1:9999/",
            "protocol_version": "2.0"
        }
    ]
)

async def main():
    # 1. Initialize the request handler
    task_store = InMemoryTaskStore()
    agent_executor = HelloWorldAgentExecutor()
    request_handler = DefaultRequestHandler(agent_executor, task_store, public_agent_card, extended_agent_card)

    # 2. Create routes for the A2A server
    agent_card_routes = create_agent_card_routes(public_agent_card)
    jsonrpc_routes = create_jsonrpc_routes(request_handler, '/')

    # Combine all routes
    routes = agent_card_routes + jsonrpc_routes

    # 3. Create a Starlette application
    app = Starlette(routes=routes)

    # 4. Run the server using Uvicorn
    print("Starting server on http://127.0.0.1:9999")
    config = uvicorn.Config(app, host='127.0.0.1', port=9999)
    server = uvicorn.Server(config)
    await server.serve()

if __name__ == "__main__":
    uvicorn.run(Starlette(routes=[
        Route("/", endpoint=lambda req: JSONResponse({"message": "A2A Server is running"}))
    ]), host='127.0.0.1', port=9999)

```

--------------------------------

### Install A2A Python SDK

Source: https://github.com/a2aproject/a2a/blob/main/docs/sdk/python/index.md

Use pip to install the a2a-sdk package.

```sh
pip install a2a-sdk
```

--------------------------------

### Install Protocol Buffers Compiler on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install the Protocol Buffers compiler (`protoc`) on Windows, preferably using WinGet.

```powershell
# Install via WinGet (recommended):
winget install Google.Protobuf

# Verify installation:
protoc --version
```

--------------------------------

### Verify A2A SDK Installation

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/2-setup.md

Verify that the A2A SDK has been installed correctly by attempting to import the `a2a` package in a Python interpreter. A success message indicates a proper setup.

```python
python -c "import a2a; print('A2A SDK imported successfully')"
```

--------------------------------

### Install Core Build Tools on macOS

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install essential build tools including `protoc`, `go`, and `jq` using Homebrew on macOS.

```bash
brew install protobuf go jq
```

--------------------------------

### Install Go Programming Language on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Install the Go programming language on Windows, recommended via WinGet or by downloading from the official website.

```powershell
# Install via WinGet:
winget install GoLang.Go

# Or download from https://golang.org/dl/
# Verify installation:
go version
```

--------------------------------

### Verify Python Installation

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Verify that Python 3 and pip are installed on your system. These are required for installing documentation dependencies.

```bash
# Verify installation:
python3 --version
pip3 --version
```

--------------------------------

### Install A2A SDK Dependencies

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/2-setup.md

Install the A2A Python SDK and its required dependencies by referencing the `requirements.txt` file located in the samples directory.

```bash
pip install -r samples/python/requirements.txt
```

--------------------------------

### Verify Python Installation on Windows

Source: https://github.com/a2aproject/a2a/blob/main/specification/json/README.md

Verify that Python and pip are installed on Windows. These are required for installing documentation dependencies.

```powershell
# Install Python from python.org or via Microsoft Store
# Verify installation:
python --version
pip --version
```

--------------------------------

### Part Object Redesign: v1.0 Examples

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Illustrates the unified Part message structure in v1.0, showing examples for text, file (URL and raw), and data content types.

```json
// Text example
{
  "text": "Hello world",
  "mediaType": "text/plain"
}

// File with URL example
{
  "url": "https://example.com/doc.pdf",
  "filename": "doc.pdf",
  "mediaType": "application/pdf"
}

// File with raw bytes example
{
  "raw": "base64encodedcontent==",
  "filename": "image.png",
  "mediaType": "image/png"
}

// Data example
{
  "data": {"key": "value"},
  "mediaType": "application/json"
}
```

--------------------------------

### Run Helloworld Server Command

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/5-start-server.md

Execute this command in your terminal from the a2a-samples directory to start the Helloworld A2A server.

```bash
python samples/python/agents/helloworld/__main__.py
```

--------------------------------

### Part Object Migration: TypeScript Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Provides a TypeScript example demonstrating the migration of Part object creation and discrimination logic from v0.3.0 to v1.0.

```typescript
// v0.3.0
const textPart = { kind: "text", text: "Hello" };
const filePart = { kind: "file", file: { fileWithUri: "https://...", mimeType: "image/png" } };
const dataPart = { kind: "data", data: { key: "value" } };

// v1.0
const textPart = { text: "Hello", mediaType: "text/plain" };
const filePart = { url: "https://...", mediaType: "image/png", filename: "image.png" };
const dataPart = { data: { key: "value" }, mediaType: "application/json" };

// Discrimination changed from kind field to member presence
if (part.kind === "text") { ... }  // v0.3.0
if ("text" in part) { ... }        // v1.0
```

--------------------------------

### Send Message Response Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Example of a successful HTTP response (200 OK) after sending a message, indicating the task status.

```http
HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "task": {
    "id": "task-uuid",
    "contextId": "context-uuid",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    }
  }
}
```

--------------------------------

### Task Pagination Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Demonstrates how to use the `pageToken` parameter to retrieve subsequent pages of task results.

```APIDOC
## GET /tasks (Pagination)

### Description
This example illustrates how to paginate through task results. When a `nextPageToken` is returned in a previous response, you can use it in a subsequent request to fetch the next set of tasks.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **contextId** (string) - Required - The ID of the context to filter tasks by.
- **pageSize** (integer) - Optional - The maximum number of tasks to return per page.
- **pageToken** (string) - Required - The token obtained from `nextPageToken` of a previous response to fetch the next page.

### Request Example
```http
GET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&pageToken=base64-encoded-cursor-token HTTP/1.1
Host: agent.example.com
Authorization: Bearer token
```

### Response
#### Success Response (200)
- **tasks** (array) - A list of task objects for the current page.
- **totalSize** (integer) - The total number of tasks available across all pages.
- **pageSize** (integer) - The number of tasks returned in this response.
- **nextPageToken** (string) - A token to retrieve the next page of results. If empty, this is the last page.

#### Response Example
```json
{
  "tasks": [
    /* ... additional tasks */
  ],
  "totalSize": 15,
  "pageSize": 10,
  "nextPageToken": "base64-encoded-next-cursor-token"
}
```
```

--------------------------------

### Part Object Redesign: v0.3.0 Examples

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Demonstrates the structure of separate Part types (TextPart, FilePart, DataPart) used in v0.3.0.

```json
// Text example
{
  "kind": "text",
  "text": "Hello world"
}

// File example
{
  "kind": "file",
  "file": {
    "fileWithUri": "https://example.com/doc.pdf",
    "mimeType": "application/pdf"
  }
}

// Data example
{
  "kind": "data",
  "data": {"key": "value"}
}
```

--------------------------------

### Send Message Request Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Example of a POST request to send a message using the HTTP+JSON protocol binding. Ensure the Content-Type is set to application/a2a+json.

```http
POST /message:send
Content-Type: application/a2a+json

{
  "message": {
    "messageId": "uuid",
    "role": "ROLE_USER",
    "parts": [{"text": "Hello"}]
  },
  "configuration": {
    "acceptedOutputModes": ["text/plain"]
  }
}
```

--------------------------------

### Paginate Task Listing

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Example demonstrating how to use `pageToken` to retrieve subsequent pages of task results. Ensure to use the `nextPageToken` from the previous response.

```http
GET /tasks?contextId=c295ea44-7543-4f78-b524-7a38915ad6e4&pageSize=10&pageToken=base64-encoded-cursor-token HTTP/1.1
Host: agent.example.com
Authorization: Bearer token
```

```json
HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "tasks": [
    /* ... additional tasks */
  ],
  "totalSize": 15,
  "pageSize": 10,
  "nextPageToken": "base64-encoded-next-cursor-token"
}
```

--------------------------------

### Multi-Turn Interaction Initial Request

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Start a conversation where the agent might need more information. Use '/message:send' for the initial request.

```http
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
Authorization: Bearer token

{
  "message": {
    "role": "ROLE_USER",
    "parts": [{"text": "Book me a flight"}],
    "messageId": "msg-1"
  }
}
```

--------------------------------

### TaskStatus Object Migration Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Illustrates the migration of the TaskStatus object from v0.3.0 to v1.0, highlighting changes in the 'state' enum and 'timestamp' format.

```json
// v0.3.0
{
  "status": {
    "state": "completed",
    "timestamp": "2024-03-15T10:15:00Z"
  }
}

// v1.0
{
  "status": {
    "state": "TASK_STATE_COMPLETED",
    "timestamp": "2024-03-15T10:15:00.000Z"
  }
}
```

--------------------------------

### Message Object Migration Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Shows the migration of the Message object from v0.3.0 to v1.0, focusing on the 'role' enum change and the new 'extensions' field.

```json
// v0.3.0
{
  "role": "user",
  "parts": [{"kind": "text", "text": "Hello"}]
}

// v1.0
{
  "role": "ROLE_USER",
  "parts": [{"text": "Hello"}],
}
```

--------------------------------

### HTTP GET Request with A2A-Version Parameter

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Clients MAY provide the A2A-Version as a request parameter instead of a header. This example demonstrates its usage in an HTTP GET request.

```http
GET /tasks/task-123?A2A-Version=1.0 HTTP/1.1
Host: agent.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json
```

--------------------------------

### HTTP GET Request with A2A-Version Header

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Clients MUST send the A2A-Version header with each request to maintain compatibility. This example shows the header usage in an HTTP GET request.

```http
GET /tasks/task-123 HTTP/1.1
Host: agent.example.com
A2A-Version: 1.0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json
```

--------------------------------

### Run Helloworld Test Client

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/6-interact-with-server.md

Execute the Python test client script from the a2a-samples directory to interact with the server.

```bash
# from the a2a-samples directory
python samples/python/agents/helloworld/test_client.py
```

--------------------------------

### SendStreamingMessage SSE Response Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Example of Server-Sent Events (SSE) data format for streaming responses from SendStreamingMessage.

```text
data: {"jsonrpc": "2.0", "id": 1, "result": { /* StreamResponse object */ }}

data: {"jsonrpc": "2.0", "id": 1, "result": { /* StreamResponse object */ }}
```

--------------------------------

### Build Documentation

Source: https://github.com/a2aproject/a2a/blob/main/CONTRIBUTING.md

Builds the project documentation, including regenerating the JSON schema and the MkDocs site.

```bash
./scripts/build_docs.sh
```

--------------------------------

### Webhook Notification Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Example of a server-sent notification to a client's webhook endpoint when a task's status changes.

```APIDOC
## POST /webhook/a2a-notifications (Server Notification)

### Description
This is an example of a notification sent by the server to a client's configured webhook URL. It informs the client about a status update for a specific task.

### Method
POST

### Endpoint
/webhook/a2a-notifications

### Parameters
#### Request Body
- **statusUpdate** (object) - Required - Contains details about the task status update.
  - **taskId** (string) - Required - The ID of the task that was updated.
  - **contextId** (string) - Required - The ID of the context the task belongs to.
  - **status** (object) - Required - The new status of the task.
    - **state** (string) - Required - The updated state of the task (e.g., TASK_STATE_COMPLETED).
    - **timestamp** (string) - Required - The timestamp when the status was updated.

### Request Example
```http
POST /webhook/a2a-notifications HTTP/1.1
Host: client.example.com
Authorization: Bearer secure-client-token-for-task-aaa
Content-Type: application/a2a+json

{
  "statusUpdate": {
    "taskId": "43667960-d455-4453-b0cf-1bae4955270d",
    "contextId": "c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "2024-03-15T18:30:00Z"
    }
  }
}
```
```

--------------------------------

### Task Validation Error Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Provides an example of a validation error response when invalid parameters are provided for task retrieval.

```APIDOC
## GET /tasks (Validation Error)

### Description
This example shows the structure of a response when the request parameters fail validation. It details which fields are invalid and provides specific error messages.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - The maximum number of tasks to return per page. Must be between 1 and 100.
- **historyLength** (integer) - Optional - The number of past status updates to include. Must be non-negative.
- **status** (string) - Optional - The status to filter tasks by. Must be a valid task state.

### Request Example
```http
GET /tasks?pageSize=150&historyLength=-5&status=TASK_STATE_RUNNING HTTP/1.1
Host: agent.example.com
Authorization: Bearer token
```

### Response
#### Error Response (400 Bad Request)
- **status** (integer) - The HTTP status code (400).
- **detail** (string) - A general description of the error (e.g., "Invalid parameters").
- **errors** (array) - A list of specific validation errors.
  - **field** (string) - The name of the field that caused the error.
  - **message** (string) - A description of the validation failure.

#### Response Example
```json
{
  "status": 400,
  "detail": "Invalid parameters",
  "errors": [
    {
      "field": "pageSize",
      "message": "Must be between 1 and 100 inclusive, got 150"
    },
    {
      "field": "historyLength",
      "message": "Must be non-negative integer, got -5"
    },
    {
      "field": "status",
      "message": "Invalid status value 'TASK_STATE_RUNNING'. Must be one of: TASK_STATE_SUBMITTED, TASK_STATE_WORKING, TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED, TASK_STATE_INPUT_REQUIRED, TASK_STATE_AUTH_REQUIRED"
    }
  ]
}
```
```

--------------------------------

### Create Virtual Environment for Docs

Source: https://github.com/a2aproject/a2a/blob/main/CONTRIBUTING.md

Creates a dedicated virtual environment for managing documentation dependencies using uv.

```bash
uv venv .doc-venv
```

--------------------------------

### Create and Activate Virtual Environment (Mac/Linux)

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/2-setup.md

Create a Python virtual environment using the built-in `venv` module and activate it. This isolates project dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
```

--------------------------------

### Build Python SDK HTML Documentation

Source: https://github.com/a2aproject/a2a/blob/main/docs/README.md

Builds the HTML version of the Python SDK documentation using Sphinx. The output will be placed in the specified API directory.

```bash
sphinx-build -b html docs/sdk/python docs/sdk/python/api
```

--------------------------------

### Agent Card with Extension Declaration

Source: https://github.com/a2aproject/a2a/blob/main/docs/topics/extensions.md

An example Agent Card demonstrating the inclusion of an AgentExtension object within AgentCapabilities. This shows how an agent declares support for a specific extension, including its URI, description, and optional parameters.

```json
{
  "name": "Magic 8-ball",
  "description": "An agent that can tell your future... maybe.",
  "version": "0.1.0",
  "url": "https://example.com/agents/eightball",
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://example.com/ext/konami-code/v1",
        "description": "Provide cheat codes to unlock new fortunes",
        "required": false,
        "params": {
          "hints": [
            "When your sims need extra cash fast",
            "You might deny it, but we've seen the evidence of those cows."
          ]
        }
      }
    ]
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "fortune",
      "name": "Fortune teller",
      "description": "Seek advice from the mystical magic 8-ball",
      "tags": ["mystical", "untrustworthy"]
    }
  ]
}
```

--------------------------------

### HTTP Request with Extension Activation

Source: https://github.com/a2aproject/a2a/blob/main/docs/topics/extensions.md

An example HTTP POST request to an agent, demonstrating how a client activates an extension by including the 'A2A-Extensions' header. The 'params' field also shows how extension-specific metadata can be passed.

```http
POST /agents/eightball HTTP/1.1
Host: example.com
Content-Type: application/json
A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 519
{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "id": "1",
  "params": {
    "message": {
      "messageId": "1",
      "role": "ROLE_USER",
      "parts": [{"text": "Oh magic 8-ball, will it rain today?"}]
    },
    "metadata": {
      "https://example.com/ext/konami-code/v1/code": "motherlode"
    }
  }
}
```

--------------------------------

### Get task

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves details of a specific task.

```APIDOC
## GET /tasks/{id}

### Description
Gets a specific task by its ID.

### Method
GET

### Endpoint
/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the task.
```

--------------------------------

### Clone A2A Samples Repository

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/2-setup.md

Clone the A2A Samples repository to your local machine. Use the `--depth 1` flag for a shallow clone to save disk space and download time.

```bash
git clone https://github.com/a2aproject/a2a-samples.git -b main --depth 1
cd a2a-samples
```

--------------------------------

### Get Extended Agent Card

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves the authenticated extended Agent Card information.

```APIDOC
## GET /extendedAgentCard

### Description
Get authenticated extended Agent Card.

### Method
GET

### Endpoint
/extendedAgentCard
```

--------------------------------

### Get Task Status

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves the current status of a specific task using its unique identifier.

```APIDOC
## GET /tasks/{id}

### Description
Get task status.

### Method
GET

### Endpoint
/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the task.

### Response
#### Success Response (200)
- **task** (object) - Information about the task.
  - **id** (string) - The unique identifier for the task.
  - **contextId** (string) - The identifier for the conversation context.
  - **status** (object) - The current status of the task.
    - **state** (string) - The state of the task (e.g., TASK_STATE_COMPLETED).

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "task": {
    "id": "task-uuid",
    "contextId": "context-uuid",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    }
  }
}
```
```

--------------------------------

### Set Gemini API Key Environment Variable

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/7-streaming-and-multiturn.md

Create a .env file to store your Gemini API key. This is required for the LangGraph example to authenticate with the Gemini API.

```bash
echo "GOOGLE_API_KEY=YOUR_API_KEY_HERE" > .env
```

--------------------------------

### Agent Card Supported Interfaces Example

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Illustrates the structure of the `supportedInterfaces` field within an Agent Card, showing how a custom protocol binding is identified by a URI.

```json
{
  "supportedInterfaces": [
    {
      "url": "wss://agent.example.com/a2a/websocket",
      "protocolBinding": "https://example.com/bindings/websocket/v1",
      "protocolVersion": "1.0"
    }
  ]
}
```

--------------------------------

### HelloWorldAgentExecutor Initialization

Source: https://github.com/a2aproject/a2a/blob/main/docs/tutorials/python/4-agent-executor.md

Initializes the HelloWorldAgentExecutor by creating an instance of the HelloWorldAgent.

```python
class HelloWorldAgentExecutor(AgentExecutor):
    def __init__(self):
        self.agent = HelloWorldAgent()
```

--------------------------------

### Get Push Notification Configuration

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves a specific push notification configuration for a task using its configuration ID.

```APIDOC
## GET /tasks/{id}/pushNotificationConfigs/{configId}

### Description
Get configuration.

### Method
GET

### Endpoint
/tasks/{id}/pushNotificationConfigs/{configId}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the task.
- **configId** (string) - Required - The unique identifier of the push notification configuration.
```

--------------------------------

### GET /.well-known/agent-card.json

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves the public agent card, which provides information about the agent's capabilities and security schemes.

```APIDOC
## GET /.well-known/agent-card.json

### Description
This endpoint allows clients to discover the public capabilities and security mechanisms supported by an agent.

### Method
GET

### Endpoint
/.well-known/agent-card.json

### Response
#### Success Response (200)
- **capabilities** (object) - Describes the agent's capabilities.
  - **extendedAgentCard** (boolean) - Indicates if an authenticated extended agent card is available.
- **securitySchemes** (object) - Defines the security schemes supported by the agent.
  - **google** (object) - Details for Google-based security.
    - **openIdConnectSecurityScheme** (object) - Configuration for OpenID Connect.
      - **openIdConnectUrl** (string) - The URL for the OpenID Connect discovery document.

### Response Example
```json
{
  "capabilities": {
    "extendedAgentCard": true
  },
  "securitySchemes": {
    "google": {
      "openIdConnectSecurityScheme": {
        "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
      }
    }
  }
}
```
```

--------------------------------

### Get Tasks by Status

Source: https://github.com/a2aproject/a2a/blob/main/docs/specification.md

Retrieves a list of tasks that match a specific status across all contexts. Supports pagination.

```APIDOC
## GET /tasks

### Description
Retrieves a list of tasks filtered by their status. This allows you to find all tasks currently in a specific state, such as 'working', across any context.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **status** (string) - Required - The status to filter tasks by (e.g., TASK_STATE_WORKING).
- **pageSize** (integer) - Optional - The maximum number of tasks to return per page. Defaults to 10.

### Request Example
```http
GET /tasks?status=TASK_STATE_WORKING&pageSize=20 HTTP/1.1
Host: agent.example.com
Authorization: Bearer token
```

### Response
#### Success Response (200)
- **tasks** (array) - A list of task objects matching the specified status.
  - **id** (string) - The unique identifier for the task.
  - **contextId** (string) - The ID of the context the task belongs to.
  - **status** (object) - The current status of the task.
    - **state** (string) - The state of the task.
    - **message** (object) - Optional details about the task's status, including role and parts.
    - **timestamp** (string) - The timestamp when the status was updated.
- **totalSize** (integer) - The total number of tasks available.
- **pageSize** (integer) - The number of tasks returned in this response.
- **nextPageToken** (string) - A token to retrieve the next page of results.

#### Response Example
```json
{
  "tasks": [
    {
      "id": "789abc-def0-1234-5678-9abcdef01234",
      "contextId": "another-context-id",
      "status": {
        "state": "TASK_STATE_WORKING",
        "message": {
          "role": "ROLE_AGENT",
          "parts": [
            {
              "text": "Processing your document analysis..."
            }
          ],
          "messageId": "msg-status-update"
        },
        "timestamp": "2024-03-15T10:20:00Z"
      }
    }
  ],
  "totalSize": 1,
  "pageSize": 20,
  "nextPageToken": ""
}
```
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/a2aproject/a2a/blob/main/CONTRIBUTING.md

Activates the virtual environment for documentation development on Unix/macOS or Windows.

```bash
source .doc-venv/bin/activate  # Unix/macOS
# .doc-venv\Scripts\activate  # Windows
```

--------------------------------

### Verify Agent Card Signature

Source: https://github.com/a2aproject/a2a/blob/main/docs/whats-new-v1.md

Provides an example of how to verify the signature of an Agent Card, ensuring its authenticity and integrity before processing.

```typescript
if (agentCard.signatures && agentCard.signatures.length > 0) {
  const verified = await verifyAgentCardSignature(agentCard);
  if (!verified) {
    throw new Error("Agent Card signature verification failed");
  }
}
```