Skip to content

feat(protocol): TaskError.error_type takes model_key_budget and model_key_auth - #695

Draft
andrewpark-scaleai wants to merge 2 commits into
mainfrom
andrew-park/rel-agent-typed-errors
Draft

andrewpark-scaleai wants to merge 2 commits into
mainfrom
andrew-park/rel-agent-typed-errors

Conversation

@andrewpark-scaleai

@andrewpark-scaleai andrewpark-scaleai commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Why

AgentEnv should say why every run failed, and heal itself where code can. Today a run whose model key is out of budget or rejected is blamed on the agent, because the protocol has no error type for it.

An agent reports a failed turn with TaskResult.failure(code, message, error_type=...), and error_type accepts only agent_error or infra_error. A key the model endpoint refuses is neither the agent's fault nor a retryable infra failure, so readers of PromptResponse.error_type cannot tell it apart without matching error text.

What

  • agentenv-framework-protocol: TaskError.error_type is now the closed type TaskErrorType, which adds model_key_budget and model_key_auth to agent_error and infra_error. The validator and every signature that took the old two-value Literal use it. TaskErrorType is exported from agentenv_protocol.a2a_agent.
  • The protocol README and agents/AGENTS.md document the two values.

The framework side needs no change. TerminalResponse.from_message already copies error_type from the data part into PromptResponse.error_type as a string, so it accepts the new values from a new agent, and an agent image built against an older protocol keeps sending agent_error exactly as today.

Design decisions and tradeoffs

  • The claude-code change moved to a follow-up, feat(claude-code): type a model key refusal as model_key_budget or model_key_auth, not agent_error #710. An agent image installs the protocol from PyPI, not from this tree, and CONTRIBUTING.md says an agent's floor rises only once the protocol it names is published. The first version of this PR raised the claude-code floor and imported TaskErrorType in the same change, so the image could not find a protocol that has it and every claude-code integration test errored. This PR now ships only the protocol and the docs. The follow-up classifies the CLI's refusal and raises the floor once a release carries this change. The tradeoff is one release of lag: until the follow-up merges, claude-code still reports a refused key as agent_error. A compatibility shim in the agent (try-import, a string fallback) would remove the lag, but it would be code that exists only to straddle one release, so I left it out.
  • New error_type values, not a new field. Every reader of PromptResponse.error_type already treats any value as "the turn errored", so verifiers keep skipping these turns. A later breaker or classifier can match the two key values exactly instead of matching text. The cost is that a reader comparing error_type == "infra_error" will not match them. Nothing in this repo does.

#698 builds on this PR and makes the framework stop retrying a step that failed with either value.

How to verify

uv run --extra dev pytest tst/unit/a2a_agent/protocol_test.py packages/agentenv-protocol/tests/test_a2a_agent.py tst/unit/agents/claude_code/test_image_contract.py -q

Result: 142 passed. test_sdk_failure_round_trips_through_platform_parser sends each new value from the protocol's TaskResult.failure through the platform parser. Without the protocol change it fails with ValueError: error_type must be 'agent_error' or 'infra_error'.

Ubuntu and others added 2 commits November 16, 2026 17:57
…th round-trips to the platform parser

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…_key_auth

An agent can now say the model endpoint refused the run's key, as out of budget or
not authorized, instead of reporting it as its own agent_error. The framework already
reads error_type as a string, so it accepts these from a new agent and nothing changes
for an agent that keeps sending agent_error.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@andrewpark-scaleai
andrewpark-scaleai force-pushed the andrew-park/rel-agent-typed-errors branch from f19f001 to 26aa29a Compare November 16, 2026 18:04
@andrewpark-scaleai andrewpark-scaleai changed the title feat(agents): type a model key refusal as model_key_budget / model_key_auth, not agent_error feat(protocol): TaskError.error_type takes model_key_budget and model_key_auth Nov 16, 2026

This branch has not been deployed

No deployments
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.

1 participant