feat: implement rich gRPC error details per A2A v1.0 spec by knapg · Pull Request #790 · a2aproject/a2a-python · GitHub
Skip to content

feat: implement rich gRPC error details per A2A v1.0 spec - #790

Merged
knapg merged 5 commits into
1.0-devfrom
knap/gRPC-Errors-Status
Mar 12, 2026
Merged

knapg merged 5 commits into
1.0-devfrom
knap/gRPC-Errors-Status

Conversation

@knapg

@knapg knapg commented Mar 9, 2026 •

Copy link
Copy Markdown
Collaborator

Description

This PR implements standard gRPC rich error handling using google.rpc.Status and google.rpc.ErrorInfo, bringing the SDK's gRPC transport fully in line with the A2A v1.0 specification.

Previously, the gRPC server appended the exception name to the string message (e.g., "TaskNotFoundError: task not found"), and the client relied on string splitting to parse the error back into a domain exception. This approach was brittle and not interoperable with standard gRPC ecosystems (proxies, gateways, etc.).

This PR replaces the legacy string-parsing heuristic entirely with strongly-typed binary metadata (grpc-status-details-bin).

  • Follow the CONTRIBUTING Guide.
  • Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
    • Important Prefixes for release-please:
      • fix: which represents bug fixes, and correlates to a SemVer patch.
      • feat: represents a new feature, and correlates to a SemVer minor.
      • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
  • Ensure the tests and linter pass (Run bash scripts/format.sh from the repository root to format)
  • Appropriate docs were updated (if necessary)

Fixes #723 🦕

@knapg
knapg requested a review from ishymko March 9, 2026 12:50
@knapg
knapg requested a review from a team as a code owner March 9, 2026 12:50
@gemini-code-assist

Copy link
Copy Markdown
Contributor

@knapg
knapg force-pushed the knap/gRPC-Errors-Status branch from 0562163 to acc32c2 Compare March 9, 2026 13:04

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request successfully implements rich gRPC error handling as per the A2A v1.0 specification, which is a great improvement for interoperability and robustness. However, the implementation of the abort_context function on the server side contains critical bugs (TypeError and AttributeError) that will cause the request handler to crash whenever an error occurs, leading to a denial of service for those requests. Additionally, metadata decoding lacks error handling for invalid UTF-8 sequences, which could also be exploited for a minor denial of service. While the overall changes are clean, well-structured, and include comprehensive tests, these critical security issues must be addressed to ensure the SDK fails securely and gracefully. There is also a minor suggestion to improve an existing test.

Comment thread src/a2a/server/request_handlers/grpc_handler.py Outdated
Comment thread src/a2a/server/request_handlers/grpc_handler.py Outdated
@knapg
knapg force-pushed the knap/gRPC-Errors-Status branch from acc32c2 to fdb156b Compare March 9, 2026 13:12
Comment thread src/a2a/utils/errors.py Outdated
Comment thread src/a2a/client/transports/grpc.py Outdated
Comment thread src/a2a/server/request_handlers/grpc_handler.py Outdated
Comment thread src/a2a/client/transports/grpc.py Outdated
@knapg
knapg force-pushed the knap/gRPC-Errors-Status branch 7 times, most recently from ec40fee to e4b237a Compare March 12, 2026 12:51
- Removed unreleased legacy string-split fallback parsing for gRPC errors.
- Refactored client and server handlers to use pure grpcio-status helpers for
  encoding/decoding google.rpc.Status to standard trailing metadata.
- Cleaned up A2A_ERROR_REASONS map to strictly contain only the 9 domain
  errors defined in the specification (removing generic JSON-RPC errors).
- Added grpcio-status to pyproject.toml dependencies.
@knapg
knapg force-pushed the knap/gRPC-Errors-Status branch from c41e359 to c536466 Compare March 12, 2026 12:58
@knapg
knapg merged commit 245eca3 into 1.0-dev Mar 12, 2026
10 checks passed
@knapg
knapg deleted the knap/gRPC-Errors-Status branch March 12, 2026 17:54
ishymko added a commit that referenced this pull request Mar 17, 2026
🤖 I have created a release *beep* *boop*
---


### ⚠ BREAKING CHANGES

* **spec**: upgrade SDK to A2A 1.0 spec and use proto-based types
([#572](#572),
[#665](#665),
[#804](#804),
[#765](#765))
* **client:** introduce ServiceParameters for extensions and include it
in ClientCallContext
([#784](#784))
* **client:** rename "callback" -> "push_notification_config"
([#749](#749))
* **client:** transport agnostic interceptors
([#796](#796))
([a910cbc](a910cbc))
* add `protocol_version` column to Task and PushNotificationConfig
models and create a migration
([#789](#789))
([2e2d431](2e2d431))
* **server:** implement `Resource Scoping` for tasks and push
notifications
([#709](#709))
([f0d4669](f0d4669))

### Features

* add GetExtendedAgentCardRequest as input parameter to
GetExtendedAgentCard method
([#767](#767))
([13a092f](13a092f))
* add validation for the JSON-RPC version
([#808](#808))
([6eb7e41](6eb7e41))
* **client:** expose close() and async context manager support on
abstract Client
([#719](#719))
([e25ba7b](e25ba7b))
* **compat:** AgentCard backward compatibility helpers and tests
([#760](#760))
([81f3494](81f3494))
* **compat:** GRPC client compatible with 0.3 server
([#779](#779))
([0ebca93](0ebca93))
* **compat:** GRPC server compatible with 0.3 client
([#772](#772))
([80d827a](80d827a))
* **compat:** legacy v0.3 protocol models, conversion logic and
utilities ([#754](#754))
([26835ad](26835ad))
* **compat:** REST and JSONRPC clients compatible with 0.3 servers
([#798](#798))
([08794f7](08794f7))
* **compat:** REST and JSONRPC servers compatible with 0.3 clients
([#795](#795))
([9856054](9856054))
* **compat:** set a2a-version header to 1.0.0
([#764](#764))
([4cb68aa](4cb68aa))
* **compat:** unify v0.3 REST url prefix and expand cross-version tests
([#820](#820))
([0925f0a](0925f0a))
* database forward compatibility: make `owner` field optional
([#812](#812))
([cc29d1f](cc29d1f))
* handle tenant in Client
([#758](#758))
([5b354e4](5b354e4))
* implement missing push notifications related methods
([#711](#711))
([041f0f5](041f0f5))
* implement rich gRPC error details per A2A v1.0 spec
([#790](#790))
([245eca3](245eca3))
* **rest:** add tenant support to rest
([#773](#773))
([4771b5a](4771b5a))
* send task as a first subscribe event
([#716](#716))
([e71ac62](e71ac62))
* **server, grpc:** Implement tenant context propagation for gRPC
requests. ([#781](#781))
([164f919](164f919))
* **server, json-rpc:** Implement tenant context propagation for
JSON-RPC requests.
([#778](#778))
([72a330d](72a330d))
* **server:** add v0.3 legacy compatibility for database models
([#783](#783))
([08c491e](08c491e))
* **spec:** add `tasks/list` method with filtering and pagination to the
specification
([#511](#511))
([d5818e5](d5818e5))
* use StreamResponse as push notifications payload
([#724](#724))
([a149a09](a149a09))
* **rest:** update REST error handling to use `google.rpc.Status`
([#838](#838))
([ea7d3ad](ea7d3ad))


### Bug Fixes

* add history length and page size validations
([#726](#726))
([e67934b](e67934b))
* allign error codes with the latest spec
([#826](#826))
([709b1ff](709b1ff))
* **client:** align send_message signature with BaseClient
([#740](#740))
([57cb529](57cb529))
* get_agent_card trailing slash when agent_card_path=""
([#799](#799))
([#800](#800))
([a55c97e](a55c97e))
* handle parsing error in REST
([#806](#806))
([bbd09f2](bbd09f2))
* Improve error handling for Timeout exceptions on REST and JSON-RPC
clients ([#690](#690))
([2acd838](2acd838))
* Improve streaming errors handling
([#576](#576))
([7ea7475](7ea7475))
* properly handle unset and zero history length
([#717](#717))
([72a1007](72a1007))
* return entire history when history_length=0
([#537](#537))
([acdc0de](acdc0de))
* return mandatory fields from list_tasks
([#710](#710))
([6132053](6132053))
* taskslist error on invalid page token and response serialization
([#814](#814))
([a102d31](a102d31))
* use correct REST path for Get Extended Agent Card operation
([#769](#769))
([ced3f99](ced3f99))
* Use POST method for REST endpoint /tasks/{id}:subscribe
([#843](#843))
([a0827d0](a0827d0))

---
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: Ivan Shymko <ishymko@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants