# Error Handling

`invoke_agent()` returns a structured result on success. On failure, it either returns an `Error` value (agentic failure) or raises an exception (framework/tool failure).

## Error (returned, not raised)

`Error` is an agentic failure — the agent reasoned through the task and concluded it could not produce the requested output. It is a return value, just like a successful result.

`Error` can arise from these scenarios:

| Cause | Description |
|---|---|
| `produce_error` | The agent calls the `produce_error` tool with a message explaining why it failed. |
| Schema validation failure | The agent produced output that does not match the expected output schema after all retries. |
| Max turns exceeded | The agent finished a step without calling `produce_output` or `produce_error` for more than the allowed number of turns. |
| Timeout exceeded | The agent did not produce output or error within the timeout period. |
| Invocation hook | An `on_invoke` hook returns a non-`None` string, aborting the agent before it starts. |
| Persistent session conflict | A request is made on a persistent session that is already active. |

When the agent calls `produce_error`, the framework treats it like any other tool call: the agent can reason about the error, attempt another approach, or retry.

## Exceptions (raised, not returned)

Exceptions represent framework or tool failures — something broke inside the execution pipeline rather than the agent failing. These propagate out of `invoke_agent()` with `raise`.

| Cause | Description |
|---|---|
| Tool call failure | A tool decorated with `@tool` raises an exception during execution. |
| Internal framework error | `ValueError` (no agent available, invalid configuration), `TimeoutError` (lock not acquired within timeout), or other unexpected conditions. |
| System prompt hook exception | A system prompt hook raises an exception during session setup. |

> **Note:** The behavior of tool exceptions — whether they propagate out of `invoke_agent()` or are caught and shown to the agent — is under discussion and may change.

## Error Propagation

In a chain of agentic objects, the behavior depends on how the call is made:

- **`invoke_agent()`** — `Error` values are returned; exceptions are raised. The caller handles each independently.
- **`invoke()` (sub-agent)** — The calling agent executes in a sandbox. If the target raises an exception from a tool call, it is raised in the sandbox. `Error` values from the target's `produce_error` are returned through `invoke()` as the result.