a2aproject / a2aproject/A2A

[Feat]: Support explicit 'Payment Required' state / HTTP 402 in A2A protocol

Abierto
#1,815 19 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Shell
Estrellas
25.7k
Forks
2.6k
Merge medio
3 d 6 h
PR fusionados (30 d)
16

Descripción

### Is your feature request related to a problem? Please describe.

At present, the A2A protocol and its specification do NOT define or reserve HTTP 402 Payment Required as a first-class signal for client-agents.

This creates ambiguity for implementers and consumers when an agent or skill intends to require payment or fee authorizations before task execution. By contrast, HTTP 401 Unauthorized and 403 Forbidden *are* explicitly defined and mapped to the authentication and authorization flows in both the `docs/specification.md` and `docs/topics/enterprise-ready.md` documentation.

Real-world agent deployments increasingly require monetization or paywall support (“payment required before continuing”), but there’s no interoperable way to communicate this as a protocol event or status.

Today, task flows that need payment often overload TASK_STATE_INPUT_REQUIRED, add custom error payloads, or invent ecosystem-specific behaviors. This leads to non-standard client UX patterns, confusion between clarification-required and payment-required, and inability for client frameworks and agents to properly surface payment steps as distinct from authentication or generic input gating.

### Describe the solution you'd like

A2A should reserve, define, and document an official way to signal “payment required” conditions. This could be:
- Explicit support for HTTP 402 in the protocol, similar to how HTTP 401 and 403 are handled for authentication/authorization
- An official task state (e.g., `TASK_STATE_PAYMENT_REQUIRED`) paralleling `TASK_STATE_INPUT_REQUIRED` and `TASK_STATE_AUTH_REQUIRED`
- Or, at a minimum, spec guidance and/or an ecosystem standard extension describing how agents should surface payment-required events, how clients should respond, and which metadata to provide (e.g., invoice, payment URL, amount, currency).

This would enable:
- Interoperable client/agent behavior for paywall flows
- Reliable error handling and UX separation of payment from input/auth flows
- Stronger support for agent monetization patterns without ecosystem fragmentation
- Consistency with other explicit protocol event states (input required, auth required, forbidden, etc.)

Reference: [google-agentic-commerce/a2a-x402](https://github.com/google-agentic-commerce/a2a-x402) explores one such extension; spec guidance could recommend an extension, native event, or best practice for common flows.

### Describe alternatives you've considered

- Continue overloading `TASK_STATE_INPUT_REQUIRED` for payment steps (semantically ambiguous)
- Use HTTP 401/403/other status codes incorrectly (potentially breaks clients)
- Invent agent-specific or platform-specific extensions (fragments the ecosystem and breaks semantic interop)
- Do nothing and let payment wall signaling remain ad-hoc

### Additional context

The addition of HTTP 402/payment-required support would bring consistency to how the protocol signals action gating, matching what’s already provided for authentication (`401`/`TASK_STATE_AUTH_REQUIRED`) and authorization (`403`). There is prior discussion on whether overloading `INPUT_REQUIRED` is semantically clear, given 401/403 have explicit status mapping.

See:
- [docs/topics/enterprise-ready.md](https://github.com/a2aproject/A2A/blob/main/docs/topics/enterprise-ready.md) §Authentication for 401/403 usage
- `TASK_STATE_INPUT_REQUIRED` sample in [specification.md](https://github.com/a2aproject/A2A/blob/main/docs/specification.md)
- Example extension: https://github.com/google-agentic-commerce/a2a-x402

Open for feedback on best-fit design (protocol, official extension, or both). Will cross-link to ongoing threads/proposals as needed.

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.