diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 94cd518fe..348a61ef3 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1378,7 +1378,8 @@ Expected execution failures are returned as `TaskResult.failure(code, message)` and become failed A2A tasks with `error_type`, `error_code`, and `error_message` in the terminal message. `error_type` is the platform classification (`agent_error` by default, or explicitly `infra_error` for a retryable -infrastructure failure); `error_code` preserves the author's machine-readable +infrastructure failure, `model_key_budget` for a model key out of budget, or +`model_key_auth` for a model key the endpoint rejects); `error_code` preserves the author's machine-readable code. An exception escaping `run()`, an invalid return value, or a result-mapping failure is logged with a correlation ID and reported as an `infra_error` with code `framework.unhandled_exception`; raw exception text is diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 5f17fed1e..4f36c1aa1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -111,6 +111,7 @@ FilePart, NativeTrajectory, TaskError, + TaskErrorType, TaskOutcome, TaskPart, TaskProgress, @@ -229,6 +230,7 @@ "SnapshotWriteObjects", "StagingStore", "TaskError", + "TaskErrorType", "TaskEventsTrajectoryRequest", "TaskObjectTrajectoryRequest", "TaskOutcome", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py index 920ec7226..980a46cca 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py @@ -14,7 +14,7 @@ from dataclasses import dataclass, field from enum import Enum from pathlib import Path -from typing import Annotated, Any, Generic, Literal, TypeAlias, TypeVar, Union +from typing import Annotated, Any, Generic, Literal, TypeAlias, TypeVar, Union, get_args from a2a.types import TaskStatusUpdateEvent from pydantic import BaseModel, ConfigDict, Field, model_validator @@ -265,15 +265,21 @@ class TaskOutcome(str, Enum): FAILED = "failed" +# model_key_budget and model_key_auth: the model endpoint refused the run's key, as out of budget or not +# authorized. Neither is the agent's fault, and a retry with the same key fails the same way. +TaskErrorType: TypeAlias = Literal["agent_error", "infra_error", "model_key_budget", "model_key_auth"] +TASK_ERROR_TYPES: frozenset[str] = frozenset(get_args(TaskErrorType)) + + @dataclass(frozen=True, slots=True, kw_only=True) class TaskError: code: str message: str - error_type: Literal["agent_error", "infra_error"] = "agent_error" + error_type: TaskErrorType = "agent_error" def __post_init__(self) -> None: - if self.error_type not in {"agent_error", "infra_error"}: - raise ValueError("error_type must be 'agent_error' or 'infra_error'") + if self.error_type not in TASK_ERROR_TYPES: + raise ValueError(f"error_type must be one of {sorted(TASK_ERROR_TYPES)}") class _TaskFailed(Exception): @@ -284,7 +290,7 @@ def __init__( code: str, message: str, *, - error_type: Literal["agent_error", "infra_error"] = "agent_error", + error_type: TaskErrorType = "agent_error", ) -> None: super().__init__(message) self.error = TaskError(code=code, message=message, error_type=error_type) @@ -423,7 +429,7 @@ def failure( code: str, message: str, *, - error_type: Literal["agent_error", "infra_error"] = "agent_error", + error_type: TaskErrorType = "agent_error", parts: Iterable[TaskPart] | None = None, ) -> "TaskResult": return ( @@ -455,7 +461,7 @@ def failed( code: str, message: str, *, - error_type: Literal["agent_error", "infra_error"] = "agent_error", + error_type: TaskErrorType = "agent_error", ) -> "TaskResultBuilder": self._outcome = TaskOutcome.FAILED self._error = TaskError(code=code, message=message, error_type=error_type) diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index 5e82d5501..5490adfb1 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -1148,6 +1148,8 @@ def test_task_result_builder_validates_and_factories_share_it() -> None: ) assert infra_failure.error is not None assert infra_failure.error.error_type == "infra_error" + for key_error in ("model_key_budget", "model_key_auth"): + assert TaskResult.failure("cli_error", "refused", error_type=key_error).error.error_type == key_error with pytest.raises(ValueError, match="error_type"): TaskResult.failure("cli_error", "failed", error_type="custom") # type: ignore[arg-type] with pytest.raises(TypeError, match="unexpected keyword argument 'details'"): diff --git a/src/agent_env/agents/AGENTS.md b/src/agent_env/agents/AGENTS.md index 0c1c0f558..9005d7420 100644 --- a/src/agent_env/agents/AGENTS.md +++ b/src/agent_env/agents/AGENTS.md @@ -53,7 +53,8 @@ terminal state, `completed`, `failed` or `canceled`. Your `run()` is one turn. `{error_type, error_code, error_message}`. A success needs at least one part, and `builder().failed(...)` adds no text part, so add one. - **Errors:** `agent_error`, the default, means the agent tried and failed; `infra_error` means the run couldn't - happen, and agent-env may retry it. An exception that escapes `run()` becomes an opaque `infra_error`, its text + happen, and agent-env may retry it; `model_key_budget` and `model_key_auth` mean the model endpoint refused the + run's key as out of budget or not authorized, which a retry with that key doesn't fix. An exception that escapes `run()` becomes an opaque `infra_error`, its text never sent. - **Context and sessions:** turns of one `context_id` run one at a time; different contexts run concurrently, and the validator relies on it, so don't serialize them. Return your runtime's conversation id as `session_ref` and the next diff --git a/tst/unit/a2a_agent/protocol_test.py b/tst/unit/a2a_agent/protocol_test.py index 4c2d803bd..9c515140d 100644 --- a/tst/unit/a2a_agent/protocol_test.py +++ b/tst/unit/a2a_agent/protocol_test.py @@ -115,17 +115,18 @@ def test_sdk_success_round_trips_through_platform_parser(): assert parsed.tool_call_count == 3 -def test_sdk_failure_round_trips_through_platform_parser(): +@pytest.mark.parametrize("error_type", ["infra_error", "model_key_budget", "model_key_auth"]) +def test_sdk_failure_round_trips_through_platform_parser(error_type): result = TaskResult.failure( "provider_rate_limited", "The provider is temporarily unavailable", - error_type="infra_error", + error_type=error_type, ) parsed = TerminalResponse.from_message(_sdk_terminal_message(result)) assert parsed.response_text == "The provider is temporarily unavailable" - assert parsed.error_type == "infra_error" + assert parsed.error_type == error_type assert parsed.error_code == "provider_rate_limited" assert parsed.error_message == "The provider is temporarily unavailable"