Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@
FilePart,
NativeTrajectory,
TaskError,
TaskErrorType,
TaskOutcome,
TaskPart,
TaskProgress,
Expand Down Expand Up @@ -229,6 +230,7 @@
"SnapshotWriteObjects",
"StagingStore",
"TaskError",
"TaskErrorType",
"TaskEventsTrajectoryRequest",
"TaskObjectTrajectoryRequest",
"TaskOutcome",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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):
Expand All @@ -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)
Expand Down Expand Up @@ -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 (
Expand Down Expand Up @@ -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)
Expand Down
2 changes: 2 additions & 0 deletions packages/agentenv-protocol/tests/test_a2a_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'"):
Expand Down
3 changes: 2 additions & 1 deletion src/agent_env/agents/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions tst/unit/a2a_agent/protocol_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
Loading