From 7fd0dcc6e43cc3ab53cb2f01e3885f2a756c6a09 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Mon, 30 Jun 2025 15:19:55 -0500 Subject: [PATCH 01/29] chore(spec): Add default value for `AgentCard.protocolVersion` (#812) - Prevents a breaking change in the Python Library --- specification/json/a2a.json | 4 +--- types/src/types.ts | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/json/a2a.json b/specification/json/a2a.json index 82212cac8..39a845d86 100644 --- a/specification/json/a2a.json +++ b/specification/json/a2a.json @@ -182,10 +182,8 @@ "type": "string" }, "protocolVersion": { + "default": "0.2.5", "description": "The version of the A2A protocol this agent supports.", - "examples": [ - "0.2.5" - ], "type": "string" }, "provider": { diff --git a/types/src/types.ts b/types/src/types.ts index c328ae6eb..2104504d8 100644 --- a/types/src/types.ts +++ b/types/src/types.ts @@ -111,7 +111,7 @@ export interface AgentInterface { export interface AgentCard { /** * The version of the A2A protocol this agent supports. - * @TJS-examples ["0.2.5"] + * @default "0.2.5" */ protocolVersion: string; /** From 8051695dd54f56a647e8ce7f5439c4b00e3981d6 Mon Sep 17 00:00:00 2001 From: DracoBlue Date: Wed, 2 Jul 2025 17:15:00 +0200 Subject: [PATCH 02/29] docs: Fixed typo (`type` is `kind` on parts) in example (#817) # Description - [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md). - [x] Make your Pull Request title in the specification. - [x] Ensure the tests and linter pass (Run `nox -s format` from the repository root to format) - [x] Appropriate docs were updated (if necessary) --- docs/specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index ea88e9c09..ad439fbd0 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -1078,7 +1078,7 @@ _If the task were longer-running, the server might initially respond with `statu "artifact": { "artifactId": "9b6934dd-37e3-4eb1-8766-962efaab63a1", "parts": [ - {"type":"text", "text": "
"} + {"kind":"text", "text": "
"} ] }, "append": false, @@ -1096,7 +1096,7 @@ _If the task were longer-running, the server might initially respond with `statu "artifact": { "artifactId": "9b6934dd-37e3-4eb1-8766-962efaab63a1", "parts": [ - {"type":"text", "text": "
"} + {"kind":"text", "text": "
"} ], }, "append": true, @@ -1115,7 +1115,7 @@ _If the task were longer-running, the server might initially respond with `statu "artifact": { "artifactId": "9b6934dd-37e3-4eb1-8766-962efaab63a1", "parts": [ - {"type":"text", "text": "
"} + {"kind":"text", "text": "
"} ] }, "append": true, From b3a725b97a2165836043c6e8202cdf625fd9ce95 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 2 Jul 2025 10:37:41 -0500 Subject: [PATCH 03/29] chore(spec): Add examples and fix spelling errors in proto (#823) --- specification/grpc/a2a.proto | 17 ++++++++++++++--- types/package-lock.json | 12 ++++++------ types/package.json | 4 ++-- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/specification/grpc/a2a.proto b/specification/grpc/a2a.proto index 057801cc3..b9dd0bad7 100644 --- a/specification/grpc/a2a.proto +++ b/specification/grpc/a2a.proto @@ -136,9 +136,9 @@ message SendMessageConfiguration { // artifact. If there are multiple turns for a task, these are stored in // history. message Task { - // Unique identifer for a task, created by the A2A server. + // Unique identifier for a task, created by the A2A server. string id = 1; - // Unique identifer for the contextual collection of interactions (tasks + // Unique identifier for the contextual collection of interactions (tasks // and messages). Created by the A2A server. string context_id = 2; // The current status of a Task, including state and a message. @@ -187,6 +187,7 @@ message TaskStatus { // A message associated with the status. Message update = 2; // Timestamp when the status was recorded. + // Example: "2023-10-27T10:00:00Z" google.protobuf.Timestamp timestamp = 3; } @@ -344,8 +345,10 @@ message AgentCard { // The version of the A2A protocol this agent supports. string protocol_version = 16; // A human readable name for the agent. + // Example: "Recipe Agent" string name = 1; - // A description of the agents domain of action/solution space. + // A description of the agent's domain of action/solution space. + // Example: "Agent that helps users with recipes and cooking." string description = 2; // A URL to the address the agent is hosted at. This represents the // preferred endpoint as declared by the agent. @@ -358,6 +361,7 @@ message AgentCard { // The service provider of the agent. AgentProvider provider = 4; // The version of the agent. + // Example: "1.0.0" string version = 5; // A url to provide additional documentation about the agent. string documentation_url = 6; @@ -387,8 +391,10 @@ message AgentCard { // Represents information about the service provider of an agent. message AgentProvider { // The providers reference url + // Example: "https://ai.google.dev" string url = 1; // The providers organization name + // Example: "Google" string organization = 2; } @@ -405,10 +411,13 @@ message AgentCapabilities { // A declaration of an extension supported by an Agent. message AgentExtension { // The URI of the extension. + // Example: "https://developers.google.com/identity/protocols/oauth2" string uri = 1; // A description of how this agent uses this extension. + // Example: "Google OAuth 2.0 authentication" string description = 2; // Whether the client must follow specific requirements of the extension. + // Example: false bool required = 3; // Optional configuration for the extension. google.protobuf.Struct params = 4; @@ -428,10 +437,12 @@ message AgentSkill { // details and behaviors. string description = 3; // A set of tags for the skill to enhance categorization/utilization. + // Example: ["cooking", "customer support", "billing"] repeated string tags = 4; // A set of example queries that this skill is designed to address. // These examples should help the caller to understand how to craft requests // to the agent to achieve specific goals. + // Example: ["I need a recipe for bread"] repeated string examples = 5; // Possible input modalities supported. repeated string input_modes = 6; diff --git a/types/package-lock.json b/types/package-lock.json index 0f3b4bb70..722e1e0b2 100644 --- a/types/package-lock.json +++ b/types/package-lock.json @@ -37,9 +37,9 @@ } }, "node_modules/@jridgewell/sourcemap-codec": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.0.tgz", - "integrity": "sha512-gv3ZRaISU3fjPAgNsriBRqGWQL6quFx04YMPW/zD8XMLsU32mhCCbfbO6KZFLjvYpCZ8zyDEgqsgf+PwPaM7GQ==", + "version": "1.5.3", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.3.tgz", + "integrity": "sha512-AiR5uKpFxP3PjO4R19kQGIMwxyRyPuXmKEEy301V1C0+1rVjS94EZQXf1QKZYN8Q0YM+estSPhmx5JwNftv6nw==", "license": "MIT" }, "node_modules/@jridgewell/trace-mapping": { @@ -83,9 +83,9 @@ "license": "MIT" }, "node_modules/@types/node": { - "version": "18.19.112", - "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.112.tgz", - "integrity": "sha512-i+Vukt9POdS/MBI7YrrkkI5fMfwFtOjphSmt4WXYLfwqsfr6z/HdCx7LqT9M7JktGob8WNgj8nFB4TbGNE4Cog==", + "version": "18.19.113", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.113.tgz", + "integrity": "sha512-TmSTE9vyebJ9vSEiU+P+0Sp4F5tMgjiEOZaQUW6wA3ODvi6uBgkHQ+EsIu0pbiKvf9QHEvyRCiaz03rV0b+IaA==", "license": "MIT", "dependencies": { "undici-types": "~5.26.4" diff --git a/types/package.json b/types/package.json index 12b330710..ac36866b6 100644 --- a/types/package.json +++ b/types/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "main": "index.js", "scripts": { - "generate": "./node_modules/.bin/typescript-json-schema tsconfig.json \"*\" --defaultNumberType integer --required > ../specification/json/a2a.json", + "generate": "./node_modules/.bin/typescript-json-schema tsconfig.json \"*\" --defaultNumberType integer --required --out ../specification/json/a2a.json", "prettier": "prettier src/types.ts --write" }, "author": "", @@ -15,4 +15,4 @@ "prettier": "^3.5.3", "typescript": "^5.3.3" } -} \ No newline at end of file +} From 426f7a88330168021d8d01b43c146563dff6d7cb Mon Sep 17 00:00:00 2001 From: bufdev <4228796+bufdev@users.noreply.github.com> Date: Wed, 2 Jul 2025 11:42:07 -0400 Subject: [PATCH 04/29] chore: Add exceptions for buf lint and upgrade buf.yaml to v2 (#786) This PR does a few cleanups to `buf.yaml`: - Upgrades `buf.yaml` to [`v2`](https://buf.build/blog/buf-cli-next-generation), which is what is generally used going forward, and matches the `buf.gen.yaml` version. In this case, virtually no changes. - Adds lint exceptions for those lint rules that do not pass `buf lint`. This now ensures that `buf lint` passes. - Updates a few comments in `buf.yaml` for clarification. - Updates the `README.md` to use `buf lint` instead of `buf build`. Note that `buf build` is implicitly run via `buf lint`. - Removes the instruction about checking for breaking changes, as there's no mechanism for this set up yet. Happy to contribute a PR to make this simple if this would be desirable. - Removes the instruction to modify `buf.yaml`. `buf.yaml` should generally never need modification. --------- Signed-off-by: bufdev --- specification/grpc/README.md | 6 ++---- specification/grpc/buf.gen.yaml | 11 +++++------ specification/grpc/buf.lock | 8 +++----- specification/grpc/buf.yaml | 21 ++++++++++++++------- 4 files changed, 24 insertions(+), 22 deletions(-) diff --git a/specification/grpc/README.md b/specification/grpc/README.md index d5f42a730..725775485 100644 --- a/specification/grpc/README.md +++ b/specification/grpc/README.md @@ -11,14 +11,12 @@ Follow the installation instructions on the official `buf` GitHub repository: ## Validation -To validate your protobuf definitions and ensure they adhere to linting rules and are free of breaking changes (if configured), run the following command from the root of this folder: +To validate your protobuf definitions and ensure they adhere to linting rules, run the following command from the root of this folder: ```sh -buf build +buf lint ``` -Modify `buf.yaml` to suit your specific requirements. - ## Code Generation `buf.gen.yaml` is configured to generate code for the following languages: diff --git a/specification/grpc/buf.gen.yaml b/specification/grpc/buf.gen.yaml index f20de668e..68bc2b0b6 100644 --- a/specification/grpc/buf.gen.yaml +++ b/specification/grpc/buf.gen.yaml @@ -4,27 +4,26 @@ # This config generates python, go and java (protobuf) source. version: v2 plugins: -# Python - - remote: buf.build/protocolbuffers/python + # Python + - remote: buf.build/protocolbuffers/python:v29.3 out: src/python - remote: buf.build/grpc/python out: src/python -# Go + # Go - remote: buf.build/protocolbuffers/go out: src/go - remote: buf.build/grpc/go out: src/go - -# Java + # Java - remote: buf.build/protocolbuffers/java out: src/java - remote: buf.build/grpc/java out: src/java -# TypeScript + # TypeScript - remote: buf.build/community/stephenh-ts-proto:v1.165.0 out: src/typescript diff --git a/specification/grpc/buf.lock b/specification/grpc/buf.lock index 2ca276594..9a4fa6cef 100644 --- a/specification/grpc/buf.lock +++ b/specification/grpc/buf.lock @@ -1,8 +1,6 @@ # Generated by buf. DO NOT EDIT. -version: v1 +version: v2 deps: - - remote: buf.build - owner: googleapis - repository: googleapis + - name: buf.build/googleapis/googleapis commit: 61b203b9a9164be9a834f58c37be6f62 - digest: shake256:e619113001d6e284ee8a92b1561e5d4ea89a47b28bf0410815cb2fa23914df8be9f1a6a98dcf069f5bc2d829a2cfb1ac614863be45cd4f8a5ad8606c5f200224 + digest: b5:7811a98b35bd2e4ae5c3ac73c8b3d9ae429f3a790da15de188dc98fc2b77d6bb10e45711f14903af9553fa9821dff256054f2e4b7795789265bc476bec2f088c diff --git a/specification/grpc/buf.yaml b/specification/grpc/buf.yaml index b4521664e..f2bd1828e 100644 --- a/specification/grpc/buf.yaml +++ b/specification/grpc/buf.yaml @@ -1,12 +1,19 @@ -version: v1 - -# Google protos dependency for a2.proto +version: v2 deps: - - buf.build/googleapis/googleapis # Common protos + # Common Protobuf types. + - buf.build/googleapis/googleapis lint: use: - - STANDARD # Indicates that all the default rules should be used. - + # Indicates that all the default rules should be used. + # See https://buf.build/docs/lint/rules for more details. + - STANDARD + except: + - PACKAGE_DIRECTORY_MATCH + - RPC_REQUEST_RESPONSE_UNIQUE + - RPC_REQUEST_STANDARD_NAME + - RPC_RESPONSE_STANDARD_NAME breaking: use: - - FILE # Indicates that breaking change detection should be done on a file level. + # Indicates that breaking change detection should be done on a file level. + # See https://buf.build/docs/breaking/rules for more details. + - FILE From 66da9d10ee87dc1f8baa20a21360bebbe7d4ff1b Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 2 Jul 2025 11:51:35 -0500 Subject: [PATCH 05/29] feat(spec): Add AGENT_CARD_WELL_KNOWN_URI to spec (#824) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prevents usage of "Magic Strings" in SDKs, which supports better adherence to the recommended path for Agent Cards. NOTE: This path might also need to be changed based on feedback in https://github.com/protocol-registries/well-known-uris/issues/66 so having a global constant would make this adjustment easier. Fixes #816 🦕 --- specification/json/a2a.json | 16 +++++++++++++++- types/src/types.ts | 14 ++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/specification/json/a2a.json b/specification/json/a2a.json index 39a845d86..b4e07b532 100644 --- a/specification/json/a2a.json +++ b/specification/json/a2a.json @@ -128,7 +128,7 @@ "type": "object" }, "AgentCard": { - "description": "An AgentCard conveys key information:\n- Overall details (version, name, description, uses)\n- Skills: A set of capabilities the agent can perform\n- Default modalities/content types supported by the agent.\n- Authentication requirements", + "description": "An AgentCard conveys key information:\n- Overall details (version, name, description, uses)\n- Skills: A set of capabilities the agent can perform\n- Default modalities/content types supported by the agent.\n- Authentication requirements\n\nThe AgentCard SHOULD be hosted at the well-known URI specified by the\n`WellKnownUris.AGENT_CARD_WELL_KNOWN_URI` constant (\"/.well-known/agent.json\").", "properties": { "additionalInterfaces": { "description": "Announcement of additional supported transports. Client can use any of\nthe supported transports.", @@ -2335,6 +2335,20 @@ "message" ], "type": "object" + }, + "WellKnownUris": { + "description": "Well-known URIs used in the A2A protocol.\nhttps://datatracker.ietf.org/doc/html/rfc8615", + "properties": { + "AGENT_CARD_WELL_KNOWN_URI": { + "const": "/.well-known/agent.json", + "description": "The well-known URI at which an AgentCard should be hosted.", + "type": "string" + } + }, + "required": [ + "AGENT_CARD_WELL_KNOWN_URI" + ], + "type": "object" } } } diff --git a/types/src/types.ts b/types/src/types.ts index 2104504d8..35baecced 100644 --- a/types/src/types.ts +++ b/types/src/types.ts @@ -2,6 +2,17 @@ * @title A2A */ +/** + * Well-known URIs used in the A2A protocol. + * https://datatracker.ietf.org/doc/html/rfc8615 + */ +export interface WellKnownUris { + /** + * The well-known URI at which an AgentCard should be hosted. + */ + AGENT_CARD_WELL_KNOWN_URI: "/.well-known/agent.json"; +} + // --8<-- [start:AgentProvider] /** * Represents the service provider of an agent. @@ -107,6 +118,9 @@ export interface AgentInterface { * - Skills: A set of capabilities the agent can perform * - Default modalities/content types supported by the agent. * - Authentication requirements + * + * The AgentCard SHOULD be hosted at the well-known URI specified by the + * `WellKnownUris.AGENT_CARD_WELL_KNOWN_URI` constant ("/.well-known/agent.json"). */ export interface AgentCard { /** From 32f3f9eb2efa40c7a1d3f3cfe7e5924e999b18f1 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Wed, 2 Jul 2025 13:09:37 -0500 Subject: [PATCH 06/29] Revert "feat(spec): Add AGENT_CARD_WELL_KNOWN_URI to spec (#824)" This reverts commit 66da9d10ee87dc1f8baa20a21360bebbe7d4ff1b. --- specification/json/a2a.json | 16 +--------------- types/src/types.ts | 14 -------------- 2 files changed, 1 insertion(+), 29 deletions(-) diff --git a/specification/json/a2a.json b/specification/json/a2a.json index b4e07b532..39a845d86 100644 --- a/specification/json/a2a.json +++ b/specification/json/a2a.json @@ -128,7 +128,7 @@ "type": "object" }, "AgentCard": { - "description": "An AgentCard conveys key information:\n- Overall details (version, name, description, uses)\n- Skills: A set of capabilities the agent can perform\n- Default modalities/content types supported by the agent.\n- Authentication requirements\n\nThe AgentCard SHOULD be hosted at the well-known URI specified by the\n`WellKnownUris.AGENT_CARD_WELL_KNOWN_URI` constant (\"/.well-known/agent.json\").", + "description": "An AgentCard conveys key information:\n- Overall details (version, name, description, uses)\n- Skills: A set of capabilities the agent can perform\n- Default modalities/content types supported by the agent.\n- Authentication requirements", "properties": { "additionalInterfaces": { "description": "Announcement of additional supported transports. Client can use any of\nthe supported transports.", @@ -2335,20 +2335,6 @@ "message" ], "type": "object" - }, - "WellKnownUris": { - "description": "Well-known URIs used in the A2A protocol.\nhttps://datatracker.ietf.org/doc/html/rfc8615", - "properties": { - "AGENT_CARD_WELL_KNOWN_URI": { - "const": "/.well-known/agent.json", - "description": "The well-known URI at which an AgentCard should be hosted.", - "type": "string" - } - }, - "required": [ - "AGENT_CARD_WELL_KNOWN_URI" - ], - "type": "object" } } } diff --git a/types/src/types.ts b/types/src/types.ts index 35baecced..2104504d8 100644 --- a/types/src/types.ts +++ b/types/src/types.ts @@ -2,17 +2,6 @@ * @title A2A */ -/** - * Well-known URIs used in the A2A protocol. - * https://datatracker.ietf.org/doc/html/rfc8615 - */ -export interface WellKnownUris { - /** - * The well-known URI at which an AgentCard should be hosted. - */ - AGENT_CARD_WELL_KNOWN_URI: "/.well-known/agent.json"; -} - // --8<-- [start:AgentProvider] /** * Represents the service provider of an agent. @@ -118,9 +107,6 @@ export interface AgentInterface { * - Skills: A set of capabilities the agent can perform * - Default modalities/content types supported by the agent. * - Authentication requirements - * - * The AgentCard SHOULD be hosted at the well-known URI specified by the - * `WellKnownUris.AGENT_CARD_WELL_KNOWN_URI` constant ("/.well-known/agent.json"). */ export interface AgentCard { /** From 754c2cc48dffb6788c9efc07df4f5aafc39ec03b Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 2 Jul 2025 14:44:11 -0500 Subject: [PATCH 07/29] docs: Add Mermaid Diagram for A2A Request Lifecycle (#827) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Screenshot 2025-07-02 at 2 32 33 PM --- docs/topics/what-is-a2a.md | 42 +++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/topics/what-is-a2a.md b/docs/topics/what-is-a2a.md index 92f57cdeb..abeeadf16 100644 --- a/docs/topics/what-is-a2a.md +++ b/docs/topics/what-is-a2a.md @@ -43,6 +43,46 @@ Adopting A2A can lead to significant advantages: By establishing common ground for agent-to-agent communication, A2A aims to accelerate the adoption and utility of AI agents across diverse industries and applications, paving the way for more powerful and collaborative AI systems. -[Watch the A2A Demo Video](https://storage.googleapis.com/gweb-developer-goog-blog-assets/original_videos/A2A_demo_v4.mp4) +## A2A Request Lifecycle + +```mermaid +sequenceDiagram + participant Client + participant A2A Server + participant Auth Server + + rect rgb(240, 240, 240) + Note over Client, A2A Server: 1. Agent Discovery + Client->>A2A Server: GET agent card eg: (/.well-known/agent-card) + A2A Server-->>Client: Returns Agent Card + end + + rect rgb(240, 240, 240) + Note over Client, Auth Server: 2. Authentication + Client->>Client: Parse Agent Card for securitySchemes + alt securityScheme is openIdConnect + Client->>Auth Server: Request token based on "authorizationUrl" and "tokenUrl" + Auth Server-->>Client: Returns JWT + end + end + + rect rgb(240, 240, 240) + Note over Client, A2A Server: 3. sendMessage API + Client->>Client: Parse Agent Card for "url" param to send API requests to. + Client->>A2A Server: POST /sendMessage (with JWT) + A2A Server->>A2A Server: Process message and create task + A2A Server-->>Client: Returns Task Response + end + + rect rgb(240, 240, 240) + Note over Client, A2A Server: 4. sendMessageStream API + Client->>A2A Server: POST /sendMessageStream (with JWT) + A2A Server-->>Client: Stream: Task (Submitted) + A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Working) + A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact A) + A2A Server-->>Client: Stream: TaskArtifactUpdateEvent (artifact B) + A2A Server-->>Client: Stream: TaskStatusUpdateEvent (Completed) + end +``` Next, learn about the [Key Concepts](./key-concepts.md) that form the foundation of the A2A protocol. From 2ed02810f6fb2eda806f12039995bb169215350f Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 2 Jul 2025 14:57:27 -0500 Subject: [PATCH 08/29] docs: Add CHANGELOG to Specification page (#828) Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/specification.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index ad439fbd0..ac2beae52 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -7,6 +7,8 @@ hide: **Version:** `{{ a2a_version }}` +See [CHANGELOG](https://github.com/a2aproject/A2A/releases) for changes made between versions. + ## 1. Introduction The Agent2Agent (A2A) Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, A2A provides a common language and interaction model. From 693356164c0f35ba978a5141a3e75f07363f5bd3 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Wed, 2 Jul 2025 15:00:53 -0500 Subject: [PATCH 09/29] docs: Update CHANGELOG to "Release Notes" --- docs/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification.md b/docs/specification.md index ac2beae52..88948bbc0 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -7,7 +7,7 @@ hide: **Version:** `{{ a2a_version }}` -See [CHANGELOG](https://github.com/a2aproject/A2A/releases) for changes made between versions. +See [Release Notes](https://github.com/a2aproject/A2A/releases) for changes made between versions. ## 1. Introduction From f17edc0b9e9d8b04ed6776b7949da69a21088c48 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Wed, 2 Jul 2025 15:47:23 -0500 Subject: [PATCH 10/29] docs: Update Redirect Links --- README.md | 2 +- docs/robots.txt | 2 +- mkdocs.yml | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b86ca49f6..1fc25e1bd 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ As AI agents become more prevalent, their ability to interoperate is crucial for ## Getting Started - 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://goo.gle/a2a) for a complete overview, the full protocol specification, tutorials, and guides. -- 📝 **View the Specification:** [A2A Protocol Specification](https://a2aproject.github.io/A2A/specification/) +- 📝 **View the Specification:** [A2A Protocol Specification](https://a2aproject.github.io/A2A/latest/specification/) - 🐍 Use the SDKs: - [A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` - [A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` diff --git a/docs/robots.txt b/docs/robots.txt index 120dc498e..d9142df23 100644 --- a/docs/robots.txt +++ b/docs/robots.txt @@ -35,4 +35,4 @@ Disallow: /_drafts/ # Specify the location of your XML sitemap. # This helps search engines discover all the pages on your site. -Sitemap: https://a2aproject.github.io/A2A/sitemap.xml +Sitemap: https://a2aproject.github.io/A2A/v0.2.5/sitemap.xml diff --git a/mkdocs.yml b/mkdocs.yml index 49c749d2c..87911bcf9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -140,7 +140,8 @@ plugins: - redirects: redirect_maps: "spec-json.md": https://raw.githubusercontent.com/a2aproject/A2A/refs/heads/main/specification/json/a2a.json - "specification/overview.md": "specification.md" + "specification/overview.md": "latest/specification.md" + "robots.txt": "v0.2.5/robots.txt" "specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card" "specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects" "specification/sample-messages.md": "specification.md#9-common-workflows-examples" From 7207200d372de167c8803e90cc5798e42b521fbc Mon Sep 17 00:00:00 2001 From: alan blount Date: Thu, 3 Jul 2025 11:09:02 -0400 Subject: [PATCH 11/29] docs: Update README.md to include Java SDK (#829) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stefano and Rod say it's ready... 💯 --- README.md | 7 ++++--- docs/index.md | 7 +++++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1fc25e1bd..4400ae283 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,10 @@ As AI agents become more prevalent, their ability to interoperate is crucial for - 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://goo.gle/a2a) for a complete overview, the full protocol specification, tutorials, and guides. - 📝 **View the Specification:** [A2A Protocol Specification](https://a2aproject.github.io/A2A/latest/specification/) -- 🐍 Use the SDKs: - - [A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` - - [A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` +- Use the SDKs: + - [🐍 A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` + - [🧑‍💻 A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` + - [☕️ A2A Java SDK](https://github.com/a2aproject/a2a-java) using maven - 🎬 Use our [samples](https://github.com/a2aproject/a2a-samples) to see A2A in action ## Contributing diff --git a/docs/index.md b/docs/index.md index a13091af0..dc27bd511 100644 --- a/docs/index.md +++ b/docs/index.md @@ -118,4 +118,11 @@ A2A and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are [:fontawesome-brands-github: GitHub Samples](https://github.com/a2aproject/a2a-samples) +- :material-code-braces:{ .lg .middle } **Download a SDK** + + [:octicons-arrow-right-24: A2A Python SDK](https://github.com/a2aproject/a2a-python) + [:octicons-arrow-right-24: A2A JS SDK](https://github.com/a2aproject/a2a-js) + [:octicons-arrow-right-24: A2A Java SDK](https://github.com/a2aproject/a2a-java) + + From 630136b5664b6a1786dfa586c9949183ad3cf1b8 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Mon, 7 Jul 2025 10:40:22 -0400 Subject: [PATCH 12/29] chore: Add .gitattributes (#840) --- .gitattributes | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..9c8407cf0 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,8 @@ +# Documentation overrides +/docs/** linguist-documentation=true +/.mkdocs/** linguist-documentation=true +/specification/json/a2a.json linguist-generated=true +noxfile.py linguist-vendored=true + +# Merge and diff setting +CHANGELOG.md merge=union From 3e8f8a5a12f0b509aaaa12eceeefc27f80beca07 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Tue, 8 Jul 2025 11:36:31 -0400 Subject: [PATCH 13/29] docs: Add 404 Redirect --- .github/scripts/deploy-404.sh | 46 +++++++++++ .github/workflows/docs.yml | 15 +++- docs/404.html | 48 ++++++++++++ mkdocs.yml | 6 +- noxfile.py | 144 ---------------------------------- 5 files changed, 110 insertions(+), 149 deletions(-) create mode 100755 .github/scripts/deploy-404.sh create mode 100644 docs/404.html delete mode 100644 noxfile.py diff --git a/.github/scripts/deploy-404.sh b/.github/scripts/deploy-404.sh new file mode 100755 index 000000000..a8feb7561 --- /dev/null +++ b/.github/scripts/deploy-404.sh @@ -0,0 +1,46 @@ +#!/bin/bash + +# Exit immediately if a command exits with a non-zero status. +set -e + +# This script deploys the custom 404.html page to the root of the gh-pages branch. +# It's designed to be called from the GitHub Actions workflow. +# +# It expects one argument: +# $1: The GitHub repository name (e.g., "a2aproject/A2A"). +# +# The script assumes that the git user name and email are already configured. + +# --- Validate Input --- +if [ -z "$1" ]; then + echo "Error: Missing required argument. Please provide the repository name (e.g., owner/repo)." + exit 1 +fi + +REPO_NAME=$1 + +echo "Deploying custom 404 page for repository: $REPO_NAME" + +# --- Deployment Logic --- +# Clone the gh-pages branch into a temporary directory +git clone --branch=gh-pages --single-branch --depth=1 "https://github.com/${REPO_NAME}" gh-pages-deploy + +# Copy the 404 page from the main branch checkout into the gh-pages clone +cp docs/404.html gh-pages-deploy/404.html + +# Navigate into the cloned directory +cd gh-pages-deploy + +# Add the 404 page to the staging area +git add 404.html + +# Commit and push only if the 404 page has actually changed +if git diff --staged --quiet; then + echo "404.html is up-to-date. No new commit needed." +else + echo "Committing and pushing updated 404.html..." + git commit -m "docs: deploy custom 404.html for redirects" + git push +fi + +echo "404 page deployment complete." diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c3a3af3c8..8306c179c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -6,6 +6,7 @@ on: - main paths: - ".github/workflows/docs.yml" + - ".github/scripts/deploy-404.sh" - "requirements-docs.txt" - "mkdocs.yml" - "docs/**" @@ -14,6 +15,7 @@ on: - main paths: - ".github/workflows/docs.yml" + - ".github/scripts/deploy-404.sh" - "requirements-docs.txt" - "mkdocs.yml" - "docs/**" @@ -34,6 +36,7 @@ jobs: - name: Checkout Code uses: actions/checkout@v4 with: + token: ${{ secrets.GITHUB_TOKEN }} fetch-depth: 0 - name: Configure Git Credentials @@ -64,8 +67,13 @@ jobs: - name: Deploy development version from main branch if: github.event_name == 'push' && github.ref == 'refs/heads/main' run: | - echo "Deploying docs from main to the 'dev' version..." - mike deploy --push --update-aliases dev + mike deploy --push --update-aliases dev latest + + echo "Setting 'latest' as the default version for the site..." + mike set-default --push latest + + # Deploy 404 page + bash .github/scripts/deploy-404.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }} - name: Deploy new release version and set as latest if: github.event_name == 'release' @@ -77,3 +85,6 @@ jobs: echo "Setting 'latest' as the default version for the site..." mike set-default --push latest + + # Call the reusable script to deploy the 404 page, passing the token + bash .github/scripts/deploy-404.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 000000000..eaffa9a16 --- /dev/null +++ b/docs/404.html @@ -0,0 +1,48 @@ + + + + + + Redirecting... + + + + +

Page Not Found

+

We are attempting to redirect you to the latest version of this page.

+

If you are not redirected automatically, please navigate to the project homepage.

+ + + diff --git a/mkdocs.yml b/mkdocs.yml index 87911bcf9..d0e1f9dad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_description: >- site_dir: site extra: - a2a_version: !ENV [MIKE_VERSION, 'local-dev'] + a2a_version: !ENV [MIKE_VERSION, 'dev'] # Navigation nav: @@ -140,8 +140,7 @@ plugins: - redirects: redirect_maps: "spec-json.md": https://raw.githubusercontent.com/a2aproject/A2A/refs/heads/main/specification/json/a2a.json - "specification/overview.md": "latest/specification.md" - "robots.txt": "v0.2.5/robots.txt" + "specification/overview.md": "specification.md" "specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card" "specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects" "specification/sample-messages.md": "specification.md#9-common-workflows-examples" @@ -188,6 +187,7 @@ plugins: - ".ruff_cache" - "node_modules" - "__pycache__" + - ".DS_Store" extra: show_value: true show_qualifiers: false diff --git a/noxfile.py b/noxfile.py deleted file mode 100644 index e5f8e4cb9..000000000 --- a/noxfile.py +++ /dev/null @@ -1,144 +0,0 @@ -# pylint: skip-file -# type: ignore -# -*- coding: utf-8 -*- -# -# Copyright 2025 Google LLC -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# https://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import os -import pathlib -import subprocess - -import nox - - -DEFAULT_PYTHON_VERSION = '3.11' - -CURRENT_DIRECTORY = pathlib.Path(__file__).parent.absolute() - -nox.options.sessions = [ - 'format', -] - -# Error if a python version is missing -nox.options.error_on_missing_interpreters = True - - -@nox.session(python=DEFAULT_PYTHON_VERSION) -def format(session): - """Format Python code using autoflake, pyupgrade, and ruff.""" - # Sort Spelling Allowlist - spelling_allow_file = '.github/actions/spelling/allow.txt' - - with open(spelling_allow_file, encoding='utf-8') as file: - unique_words = sorted(set(file)) - - with open(spelling_allow_file, 'w', encoding='utf-8') as file: - file.writelines(unique_words) - - format_all = False - - if format_all: - lint_paths_py = ['.'] - else: - target_branch = 'origin/main' - - unstaged_files = subprocess.run( - [ - 'git', - 'diff', - '--name-only', - '--diff-filter=ACMRTUXB', - target_branch, - ], - stdout=subprocess.PIPE, - text=True, - check=False, - ).stdout.splitlines() - - staged_files = subprocess.run( - [ - 'git', - 'diff', - '--cached', - '--name-only', - '--diff-filter=ACMRTUXB', - target_branch, - ], - stdout=subprocess.PIPE, - text=True, - check=False, - ).stdout.splitlines() - - committed_files = subprocess.run( - [ - 'git', - 'diff', - 'HEAD', - target_branch, - '--name-only', - '--diff-filter=ACMRTUXB', - ], - stdout=subprocess.PIPE, - text=True, - check=False, - ).stdout.splitlines() - - changed_files = sorted( - { - file - for file in (unstaged_files + staged_files + committed_files) - if os.path.isfile(file) - } - ) - - lint_paths_py = [f for f in changed_files if f.endswith('.py')] - - if not lint_paths_py: - session.log('No changed Python files to lint.') - return - - session.install( - 'types-requests', - 'pyupgrade', - 'autoflake', - 'ruff', - ) - - if lint_paths_py: - if not format_all: - session.run( - 'pyupgrade', - '--exit-zero-even-if-changed', - '--py311-plus', - *lint_paths_py, - ) - session.run( - 'autoflake', - '-i', - '-r', - '--remove-all-unused-imports', - *lint_paths_py, - ) - session.run( - 'ruff', - 'check', - '--fix-only', - *lint_paths_py, - ) - session.run( - 'ruff', - 'format', - *lint_paths_py, - ) From 7d5852b58e03fe53114e1f73dd0afaada35688bc Mon Sep 17 00:00:00 2001 From: Israel Ekpo <37992436+izzymsft@users.noreply.github.com> Date: Tue, 8 Jul 2025 11:37:37 -0400 Subject: [PATCH 14/29] docs: Add Additional Interfaces and Preferred Transport to A2A Specification Documentation (#843) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Adding Additional Interfaces and Preferred Transport to A2A Specification Documentation - added missing fields to the documentation - added missing fields to example AgentCard in the spec Fixes #842 🦕 --- docs/specification.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 88948bbc0..83c57c0d6 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -165,6 +165,8 @@ Agent Cards themselves might contain information that is considered sensitive. | `name` | `string` | Yes | Human-readable name of the agent. | | `description` | `string` | Yes | Human-readable description. [CommonMark](https://commonmark.org/) MAY be used. | | `url` | `string` | Yes | Base URL for the agent's A2A service. Must be absolute. HTTPS for production. | +| `preferredTransport` | `string` | No | The transport of the preferred endpoint. Official transports supported are JSONRPC, GRPC or HTTP+JSON | +| `additionalInterfaces` | [`AgentInterface[]`](#555-agentinterface-object) | No | Additional transports supported by the service for clients to use. | | `provider` | [`AgentProvider`](#551-agentprovider-object) | No | Information about the agent's provider. | | `iconUrl` | `string` | No | A URL to an icon for the agent. | | `version` | `string` | Yes | Agent or A2A implementation version string. | @@ -243,8 +245,21 @@ Describes a specific capability, function, or area of expertise the agent can pe | `description` | `string` | Yes | Detailed skill description. [CommonMark](https://commonmark.org/) MAY be used. | | `tags` | `string[]` | Yes | Keywords/categories for discoverability. | | `examples` | `string[]` | No | Example prompts or use cases demonstrating skill usage. | -| `inputModes` | `string[]` | No | Overrides `defaultInputModes` for this specific skill. Accepted Media Types. | -| `outputModes` | `string[]` | No | Overrides `defaultOutputModes` for this specific skill. Produced Media Types. | +| `inputModes` | `string[]` | No | Overrides `defaultInputModes` for this specific skill. Accepted Media Types. | +| `outputModes` | `string[]` | No | Overrides `defaultOutputModes` for this specific skill. Produced Media Types. | + +#### 5.5.5. `AgentInterface` Object + +Provides a declaration of a combination of the target url and the supported transport to interact with the agent. + +```ts { .no-copy } +--8<-- "types/src/types.ts:AgentInterface" +``` + +| Field Name | Type | Required | Description | +| :------------- | :------- | :------- | :----------------------------------------------------------------------- | +| `url` | `string` | Yes | The url for this interface. | +| `transport` | `string` | Yes | The transport supported by this url (one of JSONRPC, GRPC or HTTP+JSON). | ### 5.6. Sample Agent Card @@ -254,6 +269,12 @@ Describes a specific capability, function, or area of expertise the agent can pe "name": "GeoSpatial Route Planner Agent", "description": "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.", "url": "https://georoute-agent.example.com/a2a/v1", + "preferredTransport": "JSONRPC", + "additionalInterfaces" : [ + {"url": "https://georoute-agent.example.com/a2a/v1", "transport": "JSONRPC"}, + {"url": "https://georoute-agent.example.com/a2a/grpc", "transport": "GRPC"}, + {"url": "https://georoute-agent.example.com/a2a/json", "transport": "HTTP+JSON"} + ], "provider": { "organization": "Example Geo Services Inc.", "url": "https://www.examplegeoservices.com" From ea7fc30bb0dada72f150fc25e197b3a5c0aae012 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Tue, 8 Jul 2025 11:44:23 -0400 Subject: [PATCH 15/29] docs: Add Token to 404 Deployment --- .github/scripts/deploy-404.sh | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/scripts/deploy-404.sh b/.github/scripts/deploy-404.sh index a8feb7561..6b9ec91c3 100755 --- a/.github/scripts/deploy-404.sh +++ b/.github/scripts/deploy-404.sh @@ -6,24 +6,26 @@ set -e # This script deploys the custom 404.html page to the root of the gh-pages branch. # It's designed to be called from the GitHub Actions workflow. # -# It expects one argument: +# Arguments: # $1: The GitHub repository name (e.g., "a2aproject/A2A"). -# -# The script assumes that the git user name and email are already configured. +# $2: The GITHUB_TOKEN for authentication. # --- Validate Input --- -if [ -z "$1" ]; then - echo "Error: Missing required argument. Please provide the repository name (e.g., owner/repo)." +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Error: Missing required arguments." + echo "Usage: $0 " exit 1 fi REPO_NAME=$1 +GH_TOKEN=$2 echo "Deploying custom 404 page for repository: $REPO_NAME" # --- Deployment Logic --- -# Clone the gh-pages branch into a temporary directory -git clone --branch=gh-pages --single-branch --depth=1 "https://github.com/${REPO_NAME}" gh-pages-deploy +# Clone the gh-pages branch using the provided token for authentication. +# This ensures we have push access. +git clone --branch=gh-pages --single-branch --depth=1 "https://x-access-token:${GH_TOKEN}@github.com/${REPO_NAME}.git" gh-pages-deploy # Copy the 404 page from the main branch checkout into the gh-pages clone cp docs/404.html gh-pages-deploy/404.html From 49167717fbba349cf27f4f3937df50272f767b11 Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Tue, 8 Jul 2025 11:59:12 -0400 Subject: [PATCH 16/29] docs: Fix git credentials --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8306c179c..e87582854 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,8 +41,8 @@ jobs: - name: Configure Git Credentials run: | - git config user.name github-actions[bot] - git config user.email 41898282+github-actions[bot]@users.noreply.github.com + git config --global user.name github-actions[bot] + git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com - name: Setup Python uses: actions/setup-python@v5 From aeef6566e897742d6e96a7777e495c5b4b5595cf Mon Sep 17 00:00:00 2001 From: swapydapy Date: Tue, 8 Jul 2025 12:01:50 -0700 Subject: [PATCH 17/29] docs: fix task doc (#848) Fixes #836 --- docs/topics/life-of-a-task.md | 48 +++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/docs/topics/life-of-a-task.md b/docs/topics/life-of-a-task.md index 4abf83c58..d5dc7a953 100644 --- a/docs/topics/life-of-a-task.md +++ b/docs/topics/life-of-a-task.md @@ -3,17 +3,17 @@ When a message is sent to an agent, it can choose to reply with either: - A stateless `Message`. -- A stateful `Task` and zero or more `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`. +- A stateful `Task` followed by zero or more `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`. -If the response is a `Message`, the interaction is completed. On the other hand, A `Task` will keep getting updated until it is in a interrupted state (`input-required` or `auth-required`) or a terminal state (`completed`, `cancelled`, `rejected` or `failed`). +If the response is a `Message`, the interaction is completed. On the other hand, if the response is a `Task`, then the task will be processed by the agent, until it is in a interrupted state (`input-required` or `auth-required`) or a terminal state (`completed`, `cancelled`, `rejected` or `failed`). ## Context -A contextId logically composes many Tasks and independent Messages. Agent implementor can manage the llm context based on these interactions, utilizing the `contextId`. +A `contextId` logically composes many `Task` objects and independent `Message` objects. If the A2A agent uses an LLM internally, it can utilize the `contextId` to manage the LLM context. -For the first time a message is sent, agent replies back with a contextId. If the agent responded with a task, then it will also have a taskId. Clients can send subsequent messages and attach the same contextID to indicate to the agent that they are continuing their previous interaction within the same context. Client also optionally attach the taskID to indicate that the message is in continuation of that specific task. +For the first time a message is sent, agent replies back with a `contextId`. If the agent responded with a task, then it will also have a `taskId`. Clients can send subsequent messages and attach the same `contextId` to indicate to the agent, that they are continuing their previous interaction within the same context. Client can optionally attach the `taskId` to a subsequent message to indicate that the message is in continuation of that specific task. -ContextId allows collaboration over a goal or share one session across multiple tasks. +`contextId` allows collaboration over a goal or share a single contextual session across multiple tasks. ## Agent: Message or a Task @@ -21,27 +21,29 @@ Messages can be used for trivial interactions which do not require long-running So conceptually there can be three levels of agents: -1. Always responds with Messages only. Doesn't do complex state management, no long running execution and uses contextID to tie messages together. Agent most probably directly wraps around an LLM invocation and simple tools. -2. Generates a task, does more substantial work that can be tracked and runs over extended life time. -3. Generates messages and tasks. Uses messages to negotiate agent capability and scope of work for a task. Then sends task to track its execution and collaborate over task states like more input-needed, error handling, etc. +1. An agent which always responds with `Message` objects only. Doesn't do complex state management, no long running execution and uses contextID to tie messages together. Agent most probably directly wraps around an LLM invocation and simple tools. +2. Generates a `Task`, does more substantial work that can be tracked and runs over extended life time. +3. Generates both `Message` and `Task` objects. Uses messages to negotiate agent capability and scope of work for a task. Then sends `Task` object to track its execution and collaborate over task states like more input-needed, error handling, etc. -An agent can choose to always reply back with task objects and model simple responses as tasks in `completed` state. +An agent can choose to always reply back with `Task` objects and model simple responses as tasks in `completed` state. ## Task Refinements & Follow-ups -Client may want to follow up with new asks based on the results of a task, refine upon the task results. This can be modeled by starting another interaction using the same contextID as the original task. Client can further hint the agent by providing the reference to the original task using `referenceTaskIds` in `Message` object. Agent would then either create a new `Task` or a `Message`. +Clients may want to follow up with new asks based on the results of a task, and/or refine upon the task results. This can be modeled by starting another interaction using the same `contextId` as the original task. Clients can further hint the agent by providing the reference to the original task using `referenceTaskIds` in `Message` object. Agent would then respond with either a new `Task` or a `Message`. Once a task has reached a terminal state (`completed`, `cancelled`, `rejected` or `failed`), it can't be restarted. There are some benefits to this: -- **Task Immutability**: Clients can reliably reference tasks and their associated state, artifacts, and messages. This provides a clean mapping of inputs to outputs. Useful for mapping client planner nodes to task execution. -- **Clear Unit of Work**: Every new request, refinement, or follow-up becomes a distinct task, simplifying bookkeeping and allowing for granular tracking of an agent's work. +- **Task Immutability**: Clients can reliably reference tasks and their associated state, artifacts, and messages. + - This provides a clean mapping of inputs to outputs. + - Useful for mapping client orchestrator to task execution. +- **Clear Unit of Work**: Every new request, refinement, or a follow-up becomes a distinct task, simplifying bookkeeping and allowing for granular tracking of an agent's work. - Each artifact can be traced to a unit task. - - This unit of work can be referenced much more granularly by parent agents or other systems like agent optimizers. Instead of restartable tasks, where all the subsequent refinements are clubbed together and would need to resort to some kind of message index range. -- **Easier Implementation**: Agent developers follow a simple rule: always create a new task for a request referring a task in terminal state. + - This unit of work can be referenced much more granularly by parent agents or other systems like agent optimizers. In case of restartable tasks, all the subsequent refinements are combined, and any reference to an interaction would need to resort to some kind of message index range. +- **Easier Implementation**: No ambiguity for agent developers, whether to create a new task or restart an existing task. Once a task is in terminal state, any related subsequent interaction would need to be within a new task. ### Parallel Follow-ups -Parallel work is supported by having the agent create distinct, parallel tasks for each follow-up message sent within the same contextId. This allows clients to track individual sub-tasks and create new dependent tasks as soon as a prerequisite task is complete. +Parallel work is supported by having agents 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: @@ -56,22 +58,24 @@ Task 4: Based on Task 2, add a spa reservation to the hotel booking. ### Referencing Previous Artifacts -The agent is responsible for inferring the relevant artifact from the referenced task or from the contextID. The serving agent is best suited to resolve ambiguity or identify missing information. +The serving agent is responsible for inferring the relevant artifact from the referenced task or from the `contextId`. The serving agent, as the domain expert, is best suited to resolve ambiguity or identify missing information because they are the ones who generated the artifacts. -If there is ambiguity (e.g., multiple artifacts could fit the request), the agent will ask the client for clarification by returning an input-required state. The client can then specify the artifact in its response. Client can optionally populate artifact reference {artifactId, taskId} in part metadata. This allows for linkage between inputs for follow-up tasks and previous generated artifacts. +If there is ambiguity (e.g., multiple artifacts could fit the request), the agent will ask the client for clarification by returning an input-required state. The client can then specify the artifact in its response. Client can optionally populate artifact reference {artifactId, taskId} in part metadata. This allows for linkage between inputs for follow-up tasks and previously generated artifacts. This approach allows for the client implementation to be simple. ### Tracking Artifact Mutation -A follow up or refinement can result in an older artifact being modified and newer artifacts being generated. It would be good to know this linkage and maybe track all mutations of the artifact to make sure only the latest copy is used for future context. Something like a linked list, with a head as the latest. +A follow up or refinement can result in an older artifact being modified and newer artifacts being generated. It would be good to know this linkage and maybe track all mutations of the artifact to make sure only the latest copy is used for future context. Something like a linked list, with the head as the latest version of the task result. -But the client is best suited, as well as is the real decider of what it considers as a result. And in fact can reject the mutation as well. Hence, the serving agent should not own this linkage and hence does not need to be part of A2A protocol spec. The serving agent should maintain the same artifact-name when generating a refinement on the original artifact. +But the client is best suited, as well as is the real judge of what it considers as an acceptable result. And in fact can reject the mutation as well. Hence, the serving agent should not own this linkage and hence this linkage does not need to be part of A2A protocol spec. Clients can maintain the linkage on their end and show the latest version to the user. -For follow-up or refinement tasks, the client is best suited to refer to the "latest" or what it considers to be the intended artifact to be refined upon. If artifact reference is not explicitly specified, the serving agent can: +To help with the tracking, the serving agent should maintain the same artifact-name when generating a refinement on the original artifact. -Use context to figure out the latest artifact. -Or in case of ambiguity or context not supported, agent can use "input-required". +For follow-up or refinement tasks, the client is best suited to refer to the "latest" or what it considers to be the intended artifact to be refined upon. If the artifact reference is not explicitly specified, the serving agent can: + +- Use context to figure out the latest artifact. +- Or in case of ambiguity or context not supported, agent can use `input-required` task state. ### Example Follow-up From 6ba72f0d51c2e3d0728f84e9743b6d0e88730b51 Mon Sep 17 00:00:00 2001 From: pstephengoogle Date: Tue, 8 Jul 2025 14:30:48 -0600 Subject: [PATCH 18/29] fix: Update json names of gRPC objects for proper transcoding (#847) --- specification/grpc/a2a.proto | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/grpc/a2a.proto b/specification/grpc/a2a.proto index b9dd0bad7..d58f2dd3a 100644 --- a/specification/grpc/a2a.proto +++ b/specification/grpc/a2a.proto @@ -185,7 +185,7 @@ message TaskStatus { // The current state of this task TaskState state = 1; // A message associated with the status. - Message update = 2; + Message update = 2 [json_name = "message"]; // Timestamp when the status was recorded. // Example: "2023-10-27T10:00:00Z" google.protobuf.Timestamp timestamp = 3; @@ -640,7 +640,7 @@ message GetAgentCardRequest { message SendMessageResponse { oneof payload { Task task = 1; - Message msg = 2; + Message msg = 2 [json_name = "message"]; } } @@ -656,7 +656,7 @@ message SendMessageResponse { message StreamResponse { oneof payload { Task task = 1; - Message msg = 2; + Message msg = 2 [json_name = "message"]; TaskStatusUpdateEvent status_update = 3; TaskArtifactUpdateEvent artifact_update = 4; } From 6ff9d5de9e0995f3db2fc15effc550f353b08b83 Mon Sep 17 00:00:00 2001 From: Maryam Ziyad Date: Wed, 9 Jul 2025 20:20:24 +0530 Subject: [PATCH 19/29] docs: fix a typo (#851) --- docs/topics/key-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/key-concepts.md b/docs/topics/key-concepts.md index 443c453e0..270cbded1 100644 --- a/docs/topics/key-concepts.md +++ b/docs/topics/key-concepts.md @@ -60,7 +60,7 @@ The Agent2Agent (A2A) protocol is built around a set of core concepts that defin - For tasks that produce results incrementally or provide real-time progress updates. - The client initiates an interaction with the server using `message/stream`. - The server responds with an HTTP connection that remains open, over which it sends a stream of Server-Sent Events (SSE). - - These events can be `Task`, `Message`, or ``TaskStatusUpdateEvent` (for status changes) or `TaskArtifactUpdateEvent` (for new or updated artifact chunks). + - These events can be `Task`, `Message`, or `TaskStatusUpdateEvent` (for status changes) or `TaskArtifactUpdateEvent` (for new or updated artifact chunks). - This requires the server to advertise the `streaming` capability in its Agent Card. - Learn more about [Streaming & Asynchronous Operations](./streaming-and-async.md). From 74ec26167cfb8e87d71dec9a2defabbbbfab55ac Mon Sep 17 00:00:00 2001 From: alan blount Date: Fri, 11 Jul 2025 11:15:25 -0400 Subject: [PATCH 20/29] docs: Poppulo on partners.md (#862) --- docs/partners.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/partners.md b/docs/partners.md index 85c16b61a..87a1928ce 100644 --- a/docs/partners.md +++ b/docs/partners.md @@ -110,6 +110,7 @@ collaborate effectively with each other and with users. - [Pendo](https://www.pendo.io) - [PerfAI.ai](https://perfai.ai) - [Personal AI](https://personal.ai) +- [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication) - [Productive Edge](https://www.productiveedge.com/) - [Proofs](https://proofs.io) - [Publicis Sapient](https://www.publicissapient.com/) From 4cfa452039325faf1bc804219edd6f5bf20825d8 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 16 Jul 2025 16:55:52 +0100 Subject: [PATCH 21/29] docs: Add API Method transport data to Specification Docs (#849) Deployed at https://a2aproject.github.io/A2A/pr-849/specification/#71-messagesend --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: pstephengoogle --- docs/specification.md | 386 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 350 insertions(+), 36 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 83c57c0d6..dfe90e5ff 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -596,9 +596,57 @@ The A2A Server's HTTP response body **MUST** be a `JSONRPCResponse` object (or, Sends a message to an agent to initiate a new interaction or to continue an existing one. This method is suitable for synchronous request/response interactions or when client-side polling (using `tasks/get`) is acceptable for monitoring longer-running tasks. A task which has reached a terminal state (completed, canceled, rejected, or failed) can't be restarted. Sending a message to such a task will result in an error. For more information, refer to the [Life of a Task guide](./topics/life-of-a-task.md). -- **Request `params` type**: [`MessageSendParams`](#711-messagesendparams-object) -- **Response `result` type (on success)**: [`Task` | `Message`](#61-task-object) (A message object or the current or final state of the task after processing the message). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object). +
+ +=== "JSON-RPC" + - **URL:** `message/send` + - **HTTP Method:** `POST` + - **Payload**: [`MessageSendParams`](#711-messagesendparams-object) + - **Response**: [`Task` | `Message`](#61-task-object) (A message object or the current or final state of the task after processing the message). + +=== "gRPC" + - **URL:** `SendMessage` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message SendMessageRequest { + Message msg = 1; + SendMessageConfiguration configuration = 2; + } + ``` + - **Response:** + ```proto + message SendMessageResponse { + oneof payload { + Task task = 1; + Message msg = 2; + } + } + ``` + +=== "REST" + - **URL:** `/v1/message:send` + - **HTTP Method:** `POST` + - **Payload:** + ```typescript + { + message: Message, + configuration?: MessageSendConfiguration, + metadata?: { [key: string]: any } + } + ``` + - **Response:** + ```typescript + // Returns one of a message or a task + { + message?: Message, + task?: Task + } + ``` + +
+ +The `error` response for all transports in case of failure is a [`JSONRPCError`](#612-jsonrpcerror-object) or equivalent. #### 7.1.1. `MessageSendParams` Object @@ -618,14 +666,58 @@ Sends a message to an agent to initiate a new interaction or to continue an exis Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task via Server-Sent Events (SSE). This method requires the server to have `AgentCard.capabilities.streaming: true`. Just like `message/send`, a task which has reached a terminal state (completed, canceled, rejected, or failed) can't be restarted. Sending a message to such a task will result in an error. For more information, refer to the [Life of a Task guide](./topics/life-of-a-task.md). -- **Request `params` type**: [`MessageSendParams`](#711-messagesendparams-object) (same as `message/send`). -- **Response (on successful subscription)**: - - HTTP Status: `200 OK`. - - HTTP `Content-Type`: `text/event-stream`. - - HTTP Body: A stream of Server-Sent Events. Each SSE `data` field contains a [`SendStreamingMessageResponse`](#721-sendstreamingmessageresponse-object) JSON object. -- **Response (on initial subscription failure)**: - - Standard HTTP error code (e.g., 4xx, 5xx). - - The HTTP body MAY contain a standard `JSONRPCResponse` with an `error` object detailing the failure. +
+ +=== "JSON-RPC" + - **URL:** `message/stream` + - **HTTP Method:** `POST` + - **Payload**: [`MessageSendParams`](#711-messagesendparams-object) (same as `message/send`) + - **Response**: A stream of Server-Sent Events. Each SSE `data` field contains a [`SendStreamingMessageResponse`](#721-sendstreamingmessageresponse-object) + +=== "gRPC" + - **URL:** `SendStreamingMessage` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message SendMessageRequest { + Message msg = 1; + SendMessageConfiguration configuration = 2; + } + ``` + - **Response:** + ```proto + message StreamResponse { + oneof payload { + Task task; + Message msg; + TaskStatusUpdateEvent status_update; + TaskArtifactUpdateEvent artifact_update; + } + } + ``` + +=== "REST" + - **URL:** `/v1/message:stream` + - **HTTP Method:** `POST` + - **Payload:** + ```typescript + { + message: Message, + configuration?: MessageSendConfiguration, + metadata?: { [key: string]: any } + } + ``` + - **Response:** + ```typescript + { + message?: Message + task?: Task + statusUpdate?: TaskStatusUpdateEvent + artifactUpdate?: TaskArtifactUpdateEvent + } + ``` + +
#### 7.2.1. `SendStreamingMessageResponse` Object @@ -682,9 +774,34 @@ Carries a new or updated artifact (or a chunk of an artifact) generated by the t Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with `message/send`, or for fetching the final state of a task after being notified via a push notification or after an SSE stream has ended. -- **Request `params` type**: [`TaskQueryParams`](#731-taskqueryparams-object) -- **Response `result` type (on success)**: [`Task`](#61-task-object) (A snapshot of the task's current state). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., if the task ID is not found, see [`TaskNotFoundError`](#82-a2a-specific-errors)). +
+ +=== "JSON-RPC" + - **URL:** `tasks/get` + - **HTTP Method:** `POST` + - **Payload**: [`TaskQueryParams`](#731-taskqueryparams-object) + - **Response**: `Task` + +=== "gRPC" + - **URL:** `GetTask` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message GetTaskRequest { + // name=tasks/{id} + string name; + int32 history_length; + } + ``` + - **Response**: `Task` + +=== "REST" + - **URL:** `v1/tasks/{id}?historyLength={historyLength}` + - **HTTP Method:** `GET` + - **Payload:** None + - **Response**: `Task` + +
#### 7.3.1. `TaskQueryParams` Object @@ -698,13 +815,69 @@ Retrieves the current state (including status, artifacts, and optionally history | `historyLength` | `integer` | No | If positive, requests the server to include up to `N` recent messages in `Task.history`. | | `metadata` | `Record` | No | Request-specific metadata. | +### `tasks/list` + +
+ +=== "JSON-RPC" + - N/A + +=== "gRPC" + - **URL:** `ListTask` + - **HTTP Method:** `GET` + - **Payload:** + ```proto + {} + ``` + - **Response**: `repeated Task` + +=== "REST" + - **URL:** `/v1/tasks` + - **HTTP Method:** `GET` + - **Payload:** + ```typescript + {} + ``` + - **Response**: `[Task]` + +
+ ### 7.4. `tasks/cancel` Requests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage). -- **Request `params` type**: [`TaskIdParams`](#741-taskidparams-object-for-taskscancel-and-taskspushnotificationconfigget) -- **Response `result` type (on success)**: [`Task`](#61-task-object) (The state of the task after the cancellation attempt. Ideally, `Task.status.state` will be `"canceled"` if successful). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)). +
+ +=== "JSON-RPC" + - **URL:** `tasks/cancel` + - **HTTP Method:** `POST` + - **Payload**: [`TaskIdParams`](#741-taskidparams-object-for-taskscancel-and-taskspushnotificationconfigget) + - **Response**: `Task` + +=== "gRPC" + - **URL:** `CancelTask` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message CancelTaskRequest{ + // name=tasks/{id} + string name; + } + ``` + - **Response**: `Task` + +=== "REST" + - **URL:** `/v1/tasks/{id}:cancel` + - **HTTP Method:** `POST` + - **Payload:** + ```typescript + { + name: string + } + ``` + - **Response**: `Task` + +
#### 7.4.1. `TaskIdParams` Object (for `tasks/cancel` and `tasks/pushNotificationConfig/get`) @@ -723,18 +896,71 @@ A simple object containing just the task ID and optional metadata. Sets or updates the push notification configuration for a specified task. This allows the client to tell the server where and how to send asynchronous updates for the task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. -- **Request `params` type**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) -- **Response `result` type (on success)**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) (Confirms the configuration that was set. The server MAY omit or mask any sensitive details like secrets from the `authentication.credentials` field in the response). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`PushNotificationNotSupportedError`](#82-a2a-specific-errors), [`TaskNotFoundError`](#82-a2a-specific-errors), errors related to invalid `PushNotificationConfig`). +
+ +=== "JSON-RPC" + - **URL:** `tasks/pushNotificationConfig/set` + - **HTTP Method:** `POST` + - **Payload**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) + - **Response**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) + +=== "gRPC" + - **URL:** `CreateTaskPushNotification` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message SetTaskPushNotificationRequest { + TaskPushNotificationConfig config = 1; + } + ``` + - **Response**: `TaskPushNotificationConfig` + +=== "REST" + - **URL:** `/v1/tasks/{id}/pushNotificationConfigs` + - **HTTP Method:** `POST` + - **Payload:** + ```typescript + { + config: TaskPushNotificationConfig + } + ``` + - **Response**: `TaskPushNotificationConfig` + +
### 7.6. `tasks/pushNotificationConfig/get` Retrieves the current push notification configuration for a specified task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. -- **Request `params` type**: [`GetTaskPushNotificationConfigParams`](#761-gettaskpushnotificationconfigparams-object-taskspushnotificationconfigget) | [`TaskIdParams`](#741-taskidparams-object-for-taskscancel-and-taskspushnotificationconfigget) -_(Note: TaskIdParams type is deprecated for this method. Use GetTaskPushNotificationConfigParams instead.)_ -- **Response `result` type (on success)**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) (The current push notification configuration for the task. Server may return an error if no push notification configuration is associated with the task). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`PushNotificationNotSupportedError`](#82-a2a-specific-errors), [`TaskNotFoundError`](#82-a2a-specific-errors)). +
+ +=== "JSON-RPC" + - **URL:** `tasks/pushNotificationConfig/get` + - **HTTP Method:** `POST` + - **Payload**: [`GetTaskPushNotificationConfigParams`](#761-gettaskpushnotificationconfigparams-object-taskspushnotificationconfigget) + - **Response**: [`TaskPushNotificationConfig`](#610-taskpushnotificationconfig-object) + +=== "gRPC" + - **URL:** `GetTaskPushNotification` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message TaskSubscriptionRequest { + // name=tasks/{id}/pushNotification/{id} + string name; + } + ``` + - **Response**: `TaskPushNotificationConfig` + +=== "REST" + - **URL:** `/v1/tasks/{taskId}/pushNotificationConfigs/{configId}` + - **HTTP Method:** `GET` + - **Payload:** None + - **Response**: `TaskPushNotificationConfig` + +
+ +**Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`PushNotificationNotSupportedError`](#82-a2a-specific-errors), [`TaskNotFoundError`](#82-a2a-specific-errors)). #### 7.6.1. `GetTaskPushNotificationConfigParams` Object (`tasks/pushNotificationConfig/get`) @@ -754,9 +980,33 @@ A object for fetching the push notification configuration for a task. Retrieves the associated push notification configurations for a specified task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. -- **Request `params` type**: [`ListTaskPushNotificationConfigParams`](#771-listtaskpushnotificationconfigparams-object-taskspushnotificationconfiglist) -- **Response `result` type (on success)**: [`TaskPushNotificationConfig[]`](#610-taskpushnotificationconfig-object) (The push notification configurations associated with the task.). -- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`PushNotificationNotSupportedError`](#82-a2a-specific-errors), [`TaskNotFoundError`](#82-a2a-specific-errors)). +
+ +=== "JSON-RPC" + - **URL:** `tasks/pushNotificationConfig/list` + - **HTTP Method:** `POST` + - **Payload:** [`ListTaskPushNotificationConfigParams`](#771-listtaskpushnotificationconfigparams-object-taskspushnotificationconfiglist) + - **Response**: `TaskPushNotificationConfig[]` + +=== "gRPC" + - **URL:** `ListTaskPushNotification` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message ListTaskPushNotificationRequest { + // parent=tasks/{id} + string parent = 1; + } + ``` + - **Response**: `repeated TaskPushNotificationConfig` + +=== "REST" + - **URL:** `/v1/tasks/{id}/pushNotificationConfigs` + - **HTTP Method:** `GET` + - **Payload:**: None + - **Response**: `[TaskPushNotificationConfig]` + +
#### 7.7.1. `ListTaskPushNotificationConfigParams` Object (`tasks/pushNotificationConfig/list`) @@ -799,18 +1049,60 @@ Allows a client to reconnect to an SSE stream for an ongoing task after a previo The purpose is to resume receiving _subsequent_ updates. The server's behavior regarding events missed during the disconnection period (e.g., whether it attempts to backfill some missed events or only sends new ones from the point of resubscription) is implementation-dependent and not strictly defined by this specification. -- **Request `params` type**: [`TaskIdParams`](#731-taskqueryparams-object) -- **Response (on successful resubscription)**: - - HTTP Status: `200 OK`. - - HTTP `Content-Type`: `text/event-stream`. - - HTTP Body: A stream of Server-Sent Events, identical in format to `message/stream`, carrying _subsequent_ [`SendStreamingMessageResponse`](#721-sendstreamingmessageresponse-object) events for the task. -- **Response (on resubscription failure)**: - - Standard HTTP error code (e.g., 4xx, 5xx). - - The HTTP body MAY contain a standard `JSONRPCResponse` with an `error` object. Failures can occur if the task is no longer active, doesn't exist, or streaming is not supported/enabled for it. +
+ +=== "JSON-RPC" + - **URL:** `tasks/resubscribe` + - **HTTP Method:** `POST` + - **Payload**: [`TaskIdParams`](#741-taskidparams-object-for-taskscancel-and-taskspushnotificationconfigget) + - **Response**: A stream of Server-Sent Events. Each SSE `data` field contains a [`SendStreamingMessageResponse`](#721-sendstreamingmessageresponse-object) + +=== "gRPC" + - **URL:** `TaskSubscription` + - **HTTP Method:** `POST` + - **Payload:** + ```proto + message TaskSubscriptionRequest{ + // name=tasks/{id} + string name; + } + ``` + - **Response:** + ```proto + message StreamResponse { + oneof payload { + Task task; + Message msg; + TaskStatusUpdateEvent status_update; + TaskArtifactUpdateEvent artifact_update; + } + } + ``` + +=== "REST" + - **URL:** `/v1/tasks/{id}:subscribe` + - **HTTP Method:** `POST` + - **Payload:** + ```typescript + { + name: string + } + ``` + - **Response:** + ```typescript + { + message?: Message + task?: Task + statusUpdate?: TaskStatusUpdateEvent + artifactUpdate?: TaskArtifactUpdateEvent + } + ``` + +
### 7.10. `agent/authenticatedExtendedCard` -Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.supportsAuthenticatedExtendedCard` is `true`. This is an HTTP GET endpoint, not a JSON-RPC method. +Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.supportsAuthenticatedExtendedCard` is `true`. - **Endpoint URL**: `{AgentCard.url}/../agent/authenticatedExtendedCard` (relative to the base URL specified in the public Agent Card). - **HTTP Method**: `GET` @@ -823,6 +1115,28 @@ Retrieves a potentially more detailed version of the Agent Card after the client - `404 Not Found`: The `supportsAuthenticatedExtendedCard` capability is declared, but the server has not implemented this endpoint at the specified path. - `5xx Server Error`: An internal server error occurred. +
+ +=== "JSON-RPC" + - **URL:** `agent/authenticatedExtendedCard` + - **HTTP Method:** `POST` + - **Payload:** None + - **Response:** `AgentCard` + +=== "gRPC" + - **URL:** `GetAgentCard` + - **HTTP Method:** `POST` + - **Payload:** None + - **Response:** `AgentCard` + +=== "REST" + - **URL:** `/v1/card` + - **HTTP Method:** `GET` + - **Payload:** None + - **Response:** `AgentCard` + +
+ Clients retrieving this authenticated card **SHOULD** replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes. #### 7.10.1. `AuthenticatedExtendedCardParams` Object From e24498355ae970c4c56143cee0f9259f5109661a Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 16 Jul 2025 17:06:11 +0100 Subject: [PATCH 22/29] docs: Remove object tables from `specification.md` (#873) Use imports from code files to avoid having multiple copies of data --- docs/specification.md | 215 ------------------------------------------ 1 file changed, 215 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index dfe90e5ff..5f356628d 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -159,26 +159,6 @@ Agent Cards themselves might contain information that is considered sensitive. --8<-- "types/src/types.ts:AgentCard" ``` -| Field Name | Type | Required | Description | -| :---------------------------------- | :----------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `protocolVersion` | `string` | Yes | The version of the A2A protocol this agent supports. | -| `name` | `string` | Yes | Human-readable name of the agent. | -| `description` | `string` | Yes | Human-readable description. [CommonMark](https://commonmark.org/) MAY be used. | -| `url` | `string` | Yes | Base URL for the agent's A2A service. Must be absolute. HTTPS for production. | -| `preferredTransport` | `string` | No | The transport of the preferred endpoint. Official transports supported are JSONRPC, GRPC or HTTP+JSON | -| `additionalInterfaces` | [`AgentInterface[]`](#555-agentinterface-object) | No | Additional transports supported by the service for clients to use. | -| `provider` | [`AgentProvider`](#551-agentprovider-object) | No | Information about the agent's provider. | -| `iconUrl` | `string` | No | A URL to an icon for the agent. | -| `version` | `string` | Yes | Agent or A2A implementation version string. | -| `documentationUrl` | `string` | No | URL to human-readable documentation for the agent. | -| `capabilities` | [`AgentCapabilities`](#552-agentcapabilities-object) | Yes | Specifies optional A2A protocol features supported (e.g., streaming, push notifications). | -| `securitySchemes` | { [scheme: string]: [SecurityScheme](#553-securityscheme-object) } | No | Security scheme details used for authenticating with this agent. undefined implies no A2A-advertised auth (not recommended for production). | -| `security` | `{ [scheme: string]: string[]; }[]` | No | Security requirements for contacting the agent. | -| `defaultInputModes` | `string[]` | Yes | Input Media Types accepted by the agent. | -| `defaultOutputModes` | `string[]` | Yes | Output Media Types produced by the agent. | -| `skills` | [`AgentSkill[]`](#554-agentskill-object) | Yes | Array of skills. Must have at least one if the agent performs actions. | -| `supportsAuthenticatedExtendedCard` | `boolean` | No | Indicates support for retrieving a more detailed Agent Card via an authenticated endpoint. | - #### 5.5.1. `AgentProvider` Object Information about the organization or entity providing the agent. @@ -187,11 +167,6 @@ Information about the organization or entity providing the agent. --8<-- "types/src/types.ts:AgentProvider" ``` -| Field Name | Type | Required | Description | -| :------------- | :------- | :------- | :-------------------------------------- | -| `organization` | `string` | Yes | Name of the organization/entity. | -| `url` | `string` | Yes | URL for the provider's website/contact. | - #### 5.5.2. `AgentCapabilities` Object Specifies optional A2A protocol features supported by the agent. @@ -200,13 +175,6 @@ Specifies optional A2A protocol features supported by the agent. --8<-- "types/src/types.ts:AgentCapabilities" ``` -| Field Name | Type | Required | Default | Description | -| :----------------------- | :--------------- | :------- | :------ | :----------------------------------------------------------------------------------- | -| `streaming` | `boolean` | No | `false` | Indicates support for SSE streaming methods (`message/stream`, `tasks/resubscribe`). | -| `pushNotifications` | `boolean` | No | `false` | Indicates support for push notification methods (`tasks/pushNotificationConfig/*`). | -| `stateTransitionHistory` | `boolean` | No | `false` | Placeholder for future feature: exposing detailed task status change history. | -| `extensions` | [`AgentExtension`[]](#5521-agentextension-object) | No | `[]` | A list of extensions supported by this agent. | - #### 5.5.2.1. `AgentExtension` Object Specifies an extension to the A2A protocol supported by the agent. @@ -215,13 +183,6 @@ Specifies an extension to the A2A protocol supported by the agent. --8<-- "types/src/types.ts:AgentExtension" ``` -| Field Name | Type | Required | Description | -| :-------------| :-------- | :------- | :------------------------------------------------------------------------------------------ | -| `uri` | `string` | Yes | The URI for the supported extension. | -| `required` | `boolean` | No | Whether the agent requires clients to follow some protocol logic specific to the extension. Clients should expect failures when attempting to interact with a server that requires an extension the client does not support. | -| `description` | `string` | No | A description of how the extension is used by the agent. | -| `params` | `object` | No | Configuration parameters specific to the extension | - #### 5.5.3. `SecurityScheme` Object Describes the authentication requirements for accessing the agent's `url` endpoint. Refer [Sample Agent Card](#56-sample-agent-card) for an example. @@ -238,16 +199,6 @@ Describes a specific capability, function, or area of expertise the agent can pe --8<-- "types/src/types.ts:AgentSkill" ``` -| Field Name | Type | Required | Description | -| :------------ | :--------- | :------- | :----------------------------------------------------------------------------- | -| `id` | `string` | Yes | Unique skill identifier within this agent. | -| `name` | `string` | Yes | Human-readable skill name. | -| `description` | `string` | Yes | Detailed skill description. [CommonMark](https://commonmark.org/) MAY be used. | -| `tags` | `string[]` | Yes | Keywords/categories for discoverability. | -| `examples` | `string[]` | No | Example prompts or use cases demonstrating skill usage. | -| `inputModes` | `string[]` | No | Overrides `defaultInputModes` for this specific skill. Accepted Media Types. | -| `outputModes` | `string[]` | No | Overrides `defaultOutputModes` for this specific skill. Produced Media Types. | - #### 5.5.5. `AgentInterface` Object Provides a declaration of a combination of the target url and the supported transport to interact with the agent. @@ -256,11 +207,6 @@ Provides a declaration of a combination of the target url and the supported tran --8<-- "types/src/types.ts:AgentInterface" ``` -| Field Name | Type | Required | Description | -| :------------- | :------- | :------- | :----------------------------------------------------------------------- | -| `url` | `string` | Yes | The url for this interface. | -| `transport` | `string` | Yes | The transport supported by this url (one of JSONRPC, GRPC or HTTP+JSON). | - ### 5.6. Sample Agent Card ```json @@ -347,16 +293,6 @@ Represents the stateful unit of work being processed by the A2A Server for an A2 --8<-- "types/src/types.ts:Task" ``` -| Field Name | Type | Required | Description | -|:------------|:--------------------------------------| :------- | :---------------------------------------------------------------------------- | -| `id` | `string` | Yes | Server generated unique task identifier (e.g., UUID) | -| `contextId` | `string` | Yes | Server generated ID for contextual alignment across interactions | -| `status` | [`TaskStatus`](#62-taskstatus-object) | Yes | Current status of the task (state, message, timestamp). | -| `artifacts` | [`Artifact[]`](#67-artifact-object) | No | Array of outputs generated by the agent for this task. | -| `history` | [`Message[]`](#64-message-object) | No | Optional array of recent messages exchanged, if requested by `historyLength`. | -| `metadata` | `Record` | No | Arbitrary key-value metadata associated with the task. | -| `kind` | `"task"` | Yes | Type discriminator, literal value | - ### 6.2. `TaskStatus` Object Represents the current state and associated context (e.g., a message from the agent) of a `Task`. @@ -365,12 +301,6 @@ Represents the current state and associated context (e.g., a message from the ag --8<-- "types/src/types.ts:TaskStatus" ``` -| Field Name | Type | Required | Description | -| :---------- | :-------------------------------- | :------- | :--------------------------------------------------------- | -| `state` | [`TaskState`](#63-taskstate-enum) | Yes | Current lifecycle state of the task. | -| `message` | [`Message`](#64-message-object) | No | Optional message providing context for the current status. | -| `timestamp` | `string` (ISO 8601) | No | Timestamp (UTC recommended) when this status was recorded. | - ### 6.3. `TaskState` Enum Defines the possible lifecycle states of a `Task`. @@ -379,18 +309,6 @@ Defines the possible lifecycle states of a `Task`. --8<-- "types/src/types.ts:TaskState" ``` -| Value | Description | Terminal? | -| :--------------- | :-------------------------------------------------------------------------------------------------------- | :--------- | -| `submitted` | Task received by the server and acknowledged, but processing has not yet actively started. | No | -| `working` | Task is actively being processed by the agent. Client may expect further updates or a terminal state. | No | -| `input-required` | Agent requires additional input from the client/user to proceed. The task is effectively paused. | No (Pause) | -| `completed` | Task finished successfully. Results are typically available in `Task.artifacts` or `TaskStatus.message`. | Yes | -| `canceled` | Task was canceled (e.g., by a `tasks/cancel` request or server-side policy). | Yes | -| `failed` | Task terminated due to an error during processing. `TaskStatus.message` may contain error details. | Yes | -| `rejected` | Task terminated due to rejection by remote agent. `TaskStatus.message` may contain error details. | Yes | -| `auth-required` | Agent requires additional authentication from the client/user to proceed. The task is effectively paused. | No (Pause) | -| `unknown` | The state of the task cannot be determined (e.g., task ID is invalid, unknown, or has expired). | Yes | - ### 6.4. `Message` Object Represents a single communication turn or a piece of contextual information between a client and an agent. Messages are used for instructions, prompts, replies, and status updates. @@ -399,18 +317,6 @@ Represents a single communication turn or a piece of contextual information betw --8<-- "types/src/types.ts:Message" ``` -| Field Name | Type | Required | Description | -| :----------------- | :------------------------------ | :------- | :------------------------------------------------------------------------------- | -| `role` | `"user"` \| `"agent"` | Yes | Indicates the sender: `"user"` (from A2A Client) or `"agent"` (from A2A Server). | -| `parts` | [`Part[]`](#65-part-union-type) | Yes | Array of content parts. Must contain at least one part. | -| `metadata` | `Record` | No | Arbitrary key-value metadata associated with this message. | -| `extensions` | `string[]` | No | A list of extension URIs that contributed to this message. | -| `referenceTaskIds` | `string[]` | No | List of tasks referenced as contextual hint by this message. | -| `messageId` | `string` | Yes | Message identifier generated by the message sender | -| `taskId` | `string` | No | Task identifier the current message is related to | -| `contextId` | `string` | No | Context identifier the message is associated with | -| `kind` | `"message"` | Yes | Type discriminator, literal value | - ### 6.5. `Part` Union Type Represents a distinct piece of content within a `Message` or `Artifact`. A `Part` is a union type representing exportable content as either `TextPart`, `FilePart`, or `DataPart`. All `Part` types also include an optional `metadata` field (`Record`) for part-specific metadata. @@ -429,12 +335,6 @@ For conveying plain textual content. --8<-- "types/src/types.ts:TextPart" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :-------------------------------------------- | -| `kind` | `"text"` (literal) | Yes | Identifies this part as textual content. | -| `text` | `string` | Yes | The textual content of the part. | -| `metadata` | `Record` | No | Optional metadata specific to this text part. | - #### 6.5.2. `FilePart` Object For conveying file-based content. @@ -443,12 +343,6 @@ For conveying file-based content. --8<-- "types/src/types.ts:FilePart" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :---------- | :-------------------------------------------- | -| `kind` | `"file"` (literal) | Yes | Identifies this part as file content. | -| `file` | `FileWithBytes` \| `FileWithUri` | Yes | Contains the file details and data/reference. | -| `metadata` | `Record` | No | Optional metadata specific to this file part. | - #### 6.5.3. `DataPart` Object For conveying structured JSON data. Useful for forms, parameters, or any machine-readable information. @@ -457,12 +351,6 @@ For conveying structured JSON data. Useful for forms, parameters, or any machine --8<-- "types/src/types.ts:DataPart" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :-------------------------------------------------------------------------- | -| `kind` | `"data"` (literal) | Yes | Identifies this part as structured data. | -| `data` | `Record` | Yes | The structured JSON data payload (an object or an array). | -| `metadata` | `Record` | No | Optional metadata specific to this data part (e.g., reference to a schema). | - ### 6.6.1 `FileWithBytes` Object Represents the data for a file, used within a `FilePart`. @@ -471,12 +359,6 @@ Represents the data for a file, used within a `FilePart`. --8<-- "types/src/types.ts:FileWithBytes" ``` -| Field Name | Type | Required | Description | -| :--------- | :------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- | -| `name` | `string` | No | Original filename (e.g., "report.pdf"). | -| `mimeType` | `string` | No | [Media Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) (e.g., `image/png`). Strongly recommended. | -| `bytes` | `string` | Yes | Base64 encoded file content. | - ### 6.6.2 `FileWithUri` Object Represents the URI for a file, used within a `FilePart`. @@ -485,12 +367,6 @@ Represents the URI for a file, used within a `FilePart`. --8<-- "types/src/types.ts:FileWithUri" ``` -| Field Name | Type | Required | Description | -| :--------- | :------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- | -| `name` | `string` | No | Original filename (e.g., "report.pdf"). | -| `mimeType` | `string` | No | [Media Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) (e.g., `image/png`). Strongly recommended. | -| `uri` | `string` | Yes | URI (absolute URL strongly recommended) to file content. Accessibility is context-dependent. | - ### 6.7. `Artifact` Object Represents a tangible output generated by the agent during a task. Artifacts are the results or products of the agent's work. @@ -499,15 +375,6 @@ Represents a tangible output generated by the agent during a task. Artifacts are --8<-- "types/src/types.ts:Artifact" ``` -| Field Name | Type | Required | Description | -| :------------ | :------------------------------ | :------- | ------------------------------------------------------------------------------- | -| `artifactId` | `string` | Yes | Identifier for the artifact generated by the agent. | -| `name` | `string` | No | Descriptive name for the artifact. | -| `description` | `string` | No | Human-readable description of the artifact. | -| `parts` | [`Part[]`](#65-part-union-type) | Yes | Content of the artifact, as one or more `Part` objects. Must have at least one. | -| `metadata` | `Record` | No | Arbitrary key-value metadata associated with the artifact. | -| `extensions` | `string[]` | No | A list of extension URIs that contributed to this artifact. | - ### 6.8. `PushNotificationConfig` Object Configuration provided by the client to the server for sending asynchronous push notifications about task updates. @@ -516,13 +383,6 @@ Configuration provided by the client to the server for sending asynchronous push --8<-- "types/src/types.ts:PushNotificationConfig" ``` -| Field Name | Type | Required | Description | -| :--------------- | :-------------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `url` | `string` | Yes | Absolute HTTPS webhook URL for the A2A Server to POST task updates to. | -| `id` | `string` | No | Optional server-generated identifier for the push notification configuration to support multiple callbacks. | -| `token` | `string` | No | Optional client-generated opaque token for the client's webhook receiver to validate the notification (e.g., server includes it in an `X-A2A-Notification-Token` header). | -| `authentication` | [`PushNotificationAuthenticationInfo`](#69-pushnotificationauthenticationinfo-object) | No | Authentication details the A2A Server must use when calling the `url`. The client's webhook (receiver) defines these requirements. | - ### 6.9. `PushNotificationAuthenticationInfo` Object A generic structure for specifying authentication requirements, typically used within `PushNotificationConfig` to describe how the A2A Server should authenticate to the client's webhook. @@ -531,11 +391,6 @@ A generic structure for specifying authentication requirements, typically used w --8<-- "types/src/types.ts:PushNotificationAuthenticationInfo" ``` -| Field Name | Type | Required | Description | -| :------------ | :--------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `schemes` | `string[]` | Yes | Array of auth scheme names the A2A Server must use when calling the client's webhook (e.g., "Bearer", "ApiKey"). | -| `credentials` | `string` | No | Optional static credentials or scheme-specific configuration info. **Handle with EXTREME CAUTION if secrets are involved.** Prefer server-side dynamic credential fetching where possible. | - ### 6.10. `TaskPushNotificationConfig` Object Used as the `params` object for the [`tasks/pushNotificationConfig/set`](#75-taskspushnotificationconfigset) method and as the `result` object for the [`tasks/pushNotificationConfig/get`](#76-taskspushnotificationconfigget) method. @@ -544,11 +399,6 @@ Used as the `params` object for the [`tasks/pushNotificationConfig/set`](#75-tas --8<-- "types/src/types.ts:TaskPushNotificationConfig" ``` -| Field Name | Type | Required | Description | -| :----------------------- | :------------------------------------------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | -| `taskId` | `string` | Yes | The ID of the task to configure push notifications for, or retrieve configuration from. | -| `pushNotificationConfig` | [`PushNotificationConfig`](#68-pushnotificationconfig-object) | Yes | The push notification configuration. For `set`, the desired config. For `get`, the current config (secrets MAY be omitted by server). | - ### 6.11. JSON-RPC Structures A2A adheres to the standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) structures for requests and responses. @@ -580,12 +430,6 @@ When a JSON-RPC call encounters an error, the Response Object will contain an `e --8<-- "types/src/types.ts:JSONRPCError" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------- | :------- | :----------------------------------------------------------------------------------------------------------- | -| `code` | `integer` | Yes | Integer error code. See [Section 8 (Error Handling)](#8-error-handling) for standard and A2A-specific codes. | -| `message` | `string` | Yes | Short, human-readable summary of the error. | -| `data` | `any` | No | Optional additional structured information about the error. | - ## 7. Protocol RPC Methods All A2A RPC methods are invoked by the A2A Client by sending an HTTP POST request to the A2A Server's `url` (as specified in its `AgentCard`). The body of the HTTP POST request **MUST** be a `JSONRPCRequest` object, and the `Content-Type` header **MUST** be `application/json`. @@ -656,12 +500,6 @@ The `error` response for all transports in case of failure is a [`JSONRPCError`] --8<-- "types/src/types.ts:MessageSendConfiguration" ``` -| Field Name | Type | Required | Description | -| :-------------- | :-------------------------------------------------------------- | :------- | :----------------------------------------------------------------- | -| `message` | [`Message`](#64-message-object) | Yes | The message content to send. `Message.role` is typically `"user"`. | -| `configuration` | [`MessageSendConfiguration`](#711-messagesendparams-object) | No | Optional: additional message configuration | -| `metadata` | `Record` | No | Request-specific metadata. | - ### 7.2. `message/stream` Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task via Server-Sent Events (SSE). This method requires the server to have `AgentCard.capabilities.streaming: true`. Just like `message/send`, a task which has reached a terminal state (completed, canceled, rejected, or failed) can't be restarted. Sending a message to such a task will result in an error. For more information, refer to the [Life of a Task guide](./topics/life-of-a-task.md). @@ -729,12 +567,6 @@ This is the structure of the JSON object found in the `data` field of each Serve --8<-- "types/src/types.ts:SendStreamingMessageSuccessResponse" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------- | -| `jsonrpc` | `"2.0"` (literal) | Yes | JSON-RPC version string. | -| `id` | `string` \| `number` | Yes | Matches the `id` from the originating `message/stream` or `tasks/resubscribe` request. | -| `result` | **Either** `Message`
**OR** `Task`
**OR** [`TaskStatusUpdateEvent`](#722-taskstatusupdateevent-object)
**OR** [`TaskArtifactUpdateEvent`](#723-taskartifactupdateevent-object) | Yes | The event payload | - #### 7.2.2. `TaskStatusUpdateEvent` Object Carries information about a change in the task's status during streaming. This is one of the possible `result` types in a `SendStreamingMessageSuccessResponse`. @@ -743,15 +575,6 @@ Carries information about a change in the task's status during streaming. This i --8<-- "types/src/types.ts:TaskStatusUpdateEvent" ``` -| Field Name | Type | Required | Default | Description | -| :---------- | :------------------------------------ | :------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | -| `taskId` | `string` | Yes | | Task ID being updated | -| `contextId` | `string` | Yes | | Context ID the task is associated with | -| `kind` | `string`, literal | Yes | `status-update` | Type discriminator, literal value | -| `status` | [`TaskStatus`](#62-taskstatus-object) | Yes | | The new `TaskStatus` object. | -| `final` | `boolean` | No | `false` | If `true`, indicates this is the terminal status update for the current stream cycle. The server typically closes the SSE connection after this. | -| `metadata` | `Record` | No | `undefined` | Event-specific metadata. | - #### 7.2.3. `TaskArtifactUpdateEvent` Object Carries a new or updated artifact (or a chunk of an artifact) generated by the task during streaming. This is one of the possible `result` types in a `SendTaskStreamingResponse`. @@ -760,16 +583,6 @@ Carries a new or updated artifact (or a chunk of an artifact) generated by the t --8<-- "types/src/types.ts:TaskArtifactUpdateEvent" ``` -| Field Name | Type | Required | Default | Description | -| :---------- | :-------------------------------- | :------- | :---------------- | :------------------------------------------------------------------------- | -| `taskId` | `string` | Yes | | Task ID associated with the generated artifact part | -| `contextId` | `string` | Yes | | Context ID the task is associated with | -| `kind` | `string`, literal | Yes | `artifact-update` | Type discriminator, literal value | -| `artifact` | [`Artifact`](#67-artifact-object) | Yes | | The `Artifact` data. Could be a complete artifact or an incremental chunk. | -| `append` | `boolean` | No | `false` | `true` means append parts to artifact; `false` (default) means replace. | -| `lastChunk` | `boolean` | No | `false` | `true` indicates this is the final update for the artifact. | -| `metadata` | `Record` | No | `undefined` | Event-specific metadata. | - ### 7.3. `tasks/get` Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with `message/send`, or for fetching the final state of a task after being notified via a push notification or after an SSE stream has ended. @@ -809,12 +622,6 @@ Retrieves the current state (including status, artifacts, and optionally history --8<-- "types/src/types.ts:TaskQueryParams" ``` -| Field Name | Type | Required | Description | -| :-------------- | :-------------------- | :------- | :--------------------------------------------------------------------------------------- | -| `id` | `string` | Yes | The ID of the task whose current state is to be retrieved. | -| `historyLength` | `integer` | No | If positive, requests the server to include up to `N` recent messages in `Task.history`. | -| `metadata` | `Record` | No | Request-specific metadata. | - ### `tasks/list`
@@ -887,11 +694,6 @@ A simple object containing just the task ID and optional metadata. --8<-- "types/src/types.ts:TaskIdParams" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :------------------------- | -| `id` | `string` | Yes | The ID of the task. | -| `metadata` | `Record` | No | Request-specific metadata. | - ### 7.5. `tasks/pushNotificationConfig/set` Sets or updates the push notification configuration for a specified task. This allows the client to tell the server where and how to send asynchronous updates for the task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. @@ -970,12 +772,6 @@ A object for fetching the push notification configuration for a task. --8<-- "types/src/types.ts:GetTaskPushNotificationConfigParams" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :------------------------- | -| `id` | `string` | Yes | The ID of the task. | -| `pushNotificationConfigId` | `string` | No | Push notification configuration id. Server will return one of the associated configurations if config id is not specified | -| `metadata` | `Record` | No | Request-specific metadata. | - ### 7.7. `tasks/pushNotificationConfig/list` Retrieves the associated push notification configurations for a specified task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. @@ -1016,11 +812,6 @@ A object for fetching the push notification configurations for a task. --8<-- "types/src/types.ts:ListTaskPushNotificationConfigRequest" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :------------------------- | -| `id` | `string` | Yes | The ID of the task. | -| `metadata` | `Record` | No | Request-specific metadata. | - ### 7.8. `tasks/pushNotificationConfig/delete` Deletes an associated push notification configuration for a task. Requires the server to have `AgentCard.capabilities.pushNotifications: true`. @@ -1037,12 +828,6 @@ A object for deleting an associated push notification configuration for a task. --8<-- "types/src/types.ts:DeleteTaskPushNotificationConfigParams" ``` -| Field Name | Type | Required | Description | -| :--------- | :-------------------- | :------- | :------------------------- | -| `id` | `string` | Yes | The ID of the task. | -| `pushNotificationConfigId` | `string` | Yes | Push notification configuration id | -| `metadata` | `Record` | No | Request-specific metadata. | - ### 7.9. `tasks/resubscribe` Allows a client to reconnect to an SSE stream for an ongoing task after a previous connection (from `message/stream` or an earlier `tasks/resubscribe`) was interrupted. Requires the server to have `AgentCard.capabilities.streaming: true`. From 843cc27cc27375c52a0768d3850bcb09a7a90103 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 16 Jul 2025 17:20:51 +0100 Subject: [PATCH 23/29] docs: Add `PartBase` and `FileBase` to `specification.md` (#874) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #868 🦕 --- docs/specification.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 5f356628d..973ec0d3b 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -325,6 +325,10 @@ Represents a distinct piece of content within a `Message` or `Artifact`. A `Part --8<-- "types/src/types.ts:Part" ``` +```ts { .no-copy } +--8<-- "types/src/types.ts:PartBase" +``` + It **MUST** be one of the following: #### 6.5.1. `TextPart` Object @@ -351,7 +355,15 @@ For conveying structured JSON data. Useful for forms, parameters, or any machine --8<-- "types/src/types.ts:DataPart" ``` -### 6.6.1 `FileWithBytes` Object +### 6.6 `FileBase` Object + +Base entity for File Contents. + +```ts { .no-copy } +--8<-- "types/src/types.ts:FileBase" +``` + +#### 6.6.1 `FileWithBytes` Object Represents the data for a file, used within a `FilePart`. @@ -359,7 +371,7 @@ Represents the data for a file, used within a `FilePart`. --8<-- "types/src/types.ts:FileWithBytes" ``` -### 6.6.2 `FileWithUri` Object +#### 6.6.2 `FileWithUri` Object Represents the URI for a file, used within a `FilePart`. From 3990fc734283056656bab761167b085c50218960 Mon Sep 17 00:00:00 2001 From: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Date: Wed, 16 Jul 2025 17:40:41 +0100 Subject: [PATCH 24/29] chore: Add .editorconfig to set shfmt (#875) --- .editorconfig | 12 ++++++++++++ .github/workflows/linter.yaml | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..cbe784164 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +# editorconfig.org +root = true + +[*] +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.sh] +indent_style = space +indent_size = 2 diff --git a/.github/workflows/linter.yaml b/.github/workflows/linter.yaml index e6fecc196..6b77dbbf4 100644 --- a/.github/workflows/linter.yaml +++ b/.github/workflows/linter.yaml @@ -54,7 +54,7 @@ jobs: LOG_LEVEL: WARN SHELLCHECK_OPTS: -e SC1091 -e 2086 VALIDATE_ALL_CODEBASE: false - FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|\\.mkdocs/overrides/.*" + FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/).*|CODE_OF_CONDUCT.md|CHANGELOG.md|GOVERNANCE.md|\\.mkdocs/overrides/.*|docs/404.html" VALIDATE_PYTHON_BLACK: false VALIDATE_PYTHON_FLAKE8: false VALIDATE_PYTHON_ISORT: false From 96ed2d3a8320eadd6cc25137732c493a61323aee Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Wed, 16 Jul 2025 21:04:47 +0100 Subject: [PATCH 25/29] docs: Update Domain to https://a2a-protocol.org --- README.md | 4 ++-- docs/404.html | 2 +- docs/robots.txt | 2 +- mkdocs.yml | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4400ae283..7f3e0e5e2 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,8 @@ As AI agents become more prevalent, their ability to interoperate is crucial for ## Getting Started -- 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://goo.gle/a2a) for a complete overview, the full protocol specification, tutorials, and guides. -- 📝 **View the Specification:** [A2A Protocol Specification](https://a2aproject.github.io/A2A/latest/specification/) +- 📚 **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://a2a-protocol.org) for a complete overview, the full protocol specification, tutorials, and guides. +- 📝 **View the Specification:** [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/) - Use the SDKs: - [🐍 A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk` - [🧑‍💻 A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk` diff --git a/docs/404.html b/docs/404.html index eaffa9a16..83b80a9f0 100644 --- a/docs/404.html +++ b/docs/404.html @@ -33,7 +33,7 @@ // Perform the redirect window.location.replace(newPath + window.location.search + window.location.hash); } else { - window.location.replace("https://a2aproject.github.io/A2A/"); + window.location.replace('https://a2a-protocol.org/'); } })(); diff --git a/docs/robots.txt b/docs/robots.txt index d9142df23..dd13666cf 100644 --- a/docs/robots.txt +++ b/docs/robots.txt @@ -35,4 +35,4 @@ Disallow: /_drafts/ # Specify the location of your XML sitemap. # This helps search engines discover all the pages on your site. -Sitemap: https://a2aproject.github.io/A2A/v0.2.5/sitemap.xml +Sitemap: https://a2a-protocol.org/v0.2.5/sitemap.xml diff --git a/mkdocs.yml b/mkdocs.yml index d0e1f9dad..4ffc6a292 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ # Project information site_name: Agent2Agent (A2A) Protocol -site_url: https://a2aproject.github.io/A2A/ +site_url: https://a2a-protocol.org/ site_description: >- An open protocol enabling communication and interoperability between opaque agentic applications. site_dir: site From 00558c3feb15c158f08fd152222908afa84a5ffa Mon Sep 17 00:00:00 2001 From: Holt Skinner Date: Wed, 16 Jul 2025 21:10:42 +0100 Subject: [PATCH 26/29] docs: Remove Weights & Biases announcement --- .mkdocs/overrides/main.html | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/.mkdocs/overrides/main.html b/.mkdocs/overrides/main.html index 5436b42ff..7e631a3d9 100644 --- a/.mkdocs/overrides/main.html +++ b/.mkdocs/overrides/main.html @@ -1,10 +1,3 @@ {% extends "base.html" %} -{% block announce %} -
-

- Join us on July 12-13 at the Weights & Biases office in San Francisco for a - A2A/MCP Hackathon -

-
-{% endblock %} +{% block announce %}{% endblock %} From 6f1d17ba806c32f2b6fbe465be93ec13bfe7d83c Mon Sep 17 00:00:00 2001 From: kthota-g Date: Thu, 17 Jul 2025 09:10:05 -0700 Subject: [PATCH 27/29] fix: Type fix and doc clarification (#877) Release-As: 0.2.6 --------- Co-authored-by: a2a-bot Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/specification.md | 2 +- docs/topics/key-concepts.md | 3 ++- specification/json/a2a.json | 3 --- types/src/types.ts | 2 +- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 973ec0d3b..6243c4ed1 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -287,7 +287,7 @@ These objects define the structure of data exchanged within the JSON-RPC methods ### 6.1. `Task` Object -Represents the stateful unit of work being processed by the A2A Server for an A2A Client. A task encapsulates the entire interaction related to a specific goal or request. A task which has reached a terminal state (completed, canceled, rejected, or failed) can't be restarted. For more information, refer to the [Life of a Task guide](./topics/life-of-a-task.md). +Represents the stateful unit of work being processed by the A2A Server for an A2A Client. A task encapsulates the entire interaction related to a specific goal or request. A task which has reached a terminal state (completed, canceled, rejected, or failed) can't be restarted. Tasks in completed state SHOULD use artifacts for returning the generated output to the clients. For more information, refer to the [Life of a Task guide](./topics/life-of-a-task.md). ```ts { .no-copy } --8<-- "types/src/types.ts:Task" diff --git a/docs/topics/key-concepts.md b/docs/topics/key-concepts.md index 270cbded1..7677b75d2 100644 --- a/docs/topics/key-concepts.md +++ b/docs/topics/key-concepts.md @@ -31,7 +31,7 @@ The Agent2Agent (A2A) protocol is built around a set of core concepts that defin - Represents a single turn or unit of communication between a client and an agent. - Messages have a `role` (either `"user"` for client-sent messages or `"agent"` for server-sent messages) and contain one or more `Part` objects that carry the actual content. `messageId` part of the Message object is a unique identifier for each message set by the sender of the message. - - Used for conveying instructions, context, questions, answers, or status updates that are not necessarily formal `Artifacts`. + - Used for conveying instructions, context, questions, answers, or status updates that are not necessarily formal `Artifacts` that are part of a `Task`. - See details in the [Protocol Specification: Message Object](../specification.md#64-message-object). - **Part:** @@ -45,6 +45,7 @@ The Agent2Agent (A2A) protocol is built around a set of core concepts that defin - **Artifact:** - Represents a tangible output or result generated by the remote agent during the processing of a task. - Examples include generated documents, images, spreadsheets, structured data results, or any other self-contained piece of information that is a direct result of the task. + - Tasks in completed state SHOULD use artifact objects for returning the generated output to the clients. - Artifacts are composed of one or more `Part` objects and can be streamed incrementally. - See details in the [Protocol Specification: Artifact Object](../specification.md#67-artifact-object). diff --git a/specification/json/a2a.json b/specification/json/a2a.json index 39a845d86..df5df7ed2 100644 --- a/specification/json/a2a.json +++ b/specification/json/a2a.json @@ -1493,9 +1493,6 @@ "description": "Where the server should send notifications when disconnected." } }, - "required": [ - "acceptedOutputModes" - ], "type": "object" }, "MessageSendParams": { diff --git a/types/src/types.ts b/types/src/types.ts index 2104504d8..46bda6938 100644 --- a/types/src/types.ts +++ b/types/src/types.ts @@ -291,7 +291,7 @@ export interface DeleteTaskPushNotificationConfigParams extends TaskIdParams { /**Configuration for the send message request. */ export interface MessageSendConfiguration { /** Accepted output modalities by the client. */ - acceptedOutputModes: string[]; + acceptedOutputModes?: string[]; /** Number of recent messages to be retrieved. */ historyLength?: number; /** Where the server should send notifications when disconnected. */ From 05f93b5a84ab60486e6f1cd0f1f7b9017c00097b Mon Sep 17 00:00:00 2001 From: abiramit5 Date: Thu, 17 Jul 2025 22:18:30 +0530 Subject: [PATCH 28/29] docs: Add Google Analytics to Docs (#865) Google Analytics Integration: I've configured Google Analytics tracking for the documentation site by adding a new analytics block to the extra section within mkdocs.yml. --- .github/actions/spelling/allow.txt | 1 + mkdocs.yml | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt index 22dc8d662..5c0ea97ad 100644 --- a/.github/actions/spelling/allow.txt +++ b/.github/actions/spelling/allow.txt @@ -73,6 +73,7 @@ Witteveen Xca YTT YWFh +ZDS Zipkin aab aacacac diff --git a/mkdocs.yml b/mkdocs.yml index 4ffc6a292..7bea80093 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,10 @@ site_dir: site extra: a2a_version: !ENV [MIKE_VERSION, 'dev'] + analytics: + provider: google + property: G-886VW76ZDS + # Navigation nav: From 026200b38247d37ee3364cdb1fc19de4f95e9e05 Mon Sep 17 00:00:00 2001 From: "release-please[bot]" <55107282+release-please[bot]@users.noreply.github.com> Date: Thu, 17 Jul 2025 18:07:27 +0100 Subject: [PATCH 29/29] chore(main): release 0.2.6 (#825) :robot: I have created a release *beep* *boop* --- ## [0.2.6](https://github.com/a2aproject/A2A/compare/v0.2.5...v0.2.6) (2025-07-17) ### Bug Fixes * Type fix and doc clarification ([#877](https://github.com/a2aproject/A2A/issues/877)) ([6f1d17b](https://github.com/a2aproject/A2A/commit/6f1d17ba806c32f2b6fbe465be93ec13bfe7d83c)) * Update json names of gRPC objects for proper transcoding ([#847](https://github.com/a2aproject/A2A/issues/847)) ([6ba72f0](https://github.com/a2aproject/A2A/commit/6ba72f0d51c2e3d0728f84e9743b6d0e88730b51)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com> --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 396ae351d..58b5ad33c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [0.2.6](https://github.com/a2aproject/A2A/compare/v0.2.5...v0.2.6) (2025-07-17) + + +### Bug Fixes + +* Type fix and doc clarification ([#877](https://github.com/a2aproject/A2A/issues/877)) ([6f1d17b](https://github.com/a2aproject/A2A/commit/6f1d17ba806c32f2b6fbe465be93ec13bfe7d83c)) +* Update json names of gRPC objects for proper transcoding ([#847](https://github.com/a2aproject/A2A/issues/847)) ([6ba72f0](https://github.com/a2aproject/A2A/commit/6ba72f0d51c2e3d0728f84e9743b6d0e88730b51)) + ## [0.2.5](https://github.com/a2aproject/A2A/compare/v0.2.4...v0.2.5) (2025-06-30)