[Feat]: Surfacing error details for failed Tasks
- Lingua principale
- Shell
- Stelle
- 25.7k
- Fork
- 2.6k
- Merge medio
- 3g 6h
- PR unite (30g)
- 16
Descrizione
### Is your feature request related to a problem? Please describe.
The spec defines error structures for synchronous responses. But in my experience in helping design an application based on the spec, there's a need for some definition for how to surface errors that occur during asynchronous handling of a Task. When a Task state changes to `failed` (or even `cancelled` or `rejected`), how is information about the cause(s) of that failure to be provided to the client?
Example scenario:
```
Client -> Agent: [message send]
Client <- Agent: [task in `working` state]
Client -> Agent: [task get]
Client <- Agent: [task in `working` state]
Agent (async processing): ** error condition, task failed **
Client -> Agent: [task get]
Client <- Agent: [task in `failed` state]
Client: (no visibility into root cause)
```
### Describe the solution you'd like
Define an optional `causes` array in `TaskStatus`, which could be used to describe conditions (including but not limited to errors) that influenced the change to the Task's status. This would facilitate troubleshooting and tracing of root causes of asynchronous task state transitions.
Each element of the array would be a core object of a union type called `Cause` (or `TaskStatusCause`).
`Error` would be one type of `Cause`, and perhaps `NonError` could be a generic stand-in for use with a non-terminal or non-error `TaskState`. Extensions could define other types of `Cause` compatible with the root model definition.
`Cause` would follow the established A2A error structure: `code` (string or numeric), `message` (or `description`, to distinguish from the `Message` object), and a flexible and optional `details` object.
The advantage of this approach is having a consistent, lowest-common-denominator definition of how to propagate asynchronous error / root-cause information between agents without requiring them to support any additional shared extensions.
### Describe alternatives you've considered
An alternative is to acknowledge the problem in the A2A specification but leave the definition of structures and mechanisms to each application implementation via the extensions mechanism (e.g., defining certain metadata to be returned in the `TaskStatus.message` object when certain custom extensions are activated).
Advantage of this approach is its simplicity and deference to application implementation needs, while alerting implementers that it is intentionally left to them to define (and not just an oversight in the specification). Downside is that it invites nonstandard ways of defining error / root-cause information, and requires clients to specifically request those extensions in every request.
I also considered limiting the `Cause` approach just to `Error`, but it seems more complicated to try to special-case the applicability of that object to certain `TaskState` values (`failed`, `rejected`, `cancelled`) but not others.
### Additional context
_No response_
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.