Errors

Concepts: Errors and interruptions.

AlpineAgentsError

Bases: Exception

Common parent of the errors alpineagents raises itself: provider failures (ProviderError and its subclasses), OutputError, NoHumanError and MCPConnectionError.

A wrong use of the library (a bad argument, a mistake in a @tool function or a @loop) raises a plain TypeError or ValueError as early as possible instead: when the Agent is created, @tool or @loop is applied, or a method is called. Its message says what is wrong, then Fix: and Example: lines.

Nothing is swallowed: exceptions from tools, from the body of a loop and from until functions propagate as they are, unless you turn them into results with ToolError or @tool(exception_handler=...).

ProviderError

Bases: AlpineAgentsError

The model API failed even after SDK retries. The original SDK exception is in __cause__.

RateLimitError, AuthError and ContextTooLongError are subclasses. The SDK retries only a request whose reply has not started: a stream that drops halfway raises ProviderError and is not retried.

RateLimitError

Bases: ProviderError

The provider's rate limit (429).

ContextTooLongError

Bases: ProviderError

The context is larger than the model's context window. Add a compaction block such as compact_if_full to the loop.

AuthError

Bases: ProviderError

Authentication failed (missing API key, wrong key, no permission).

OutputError

Bases: AlpineAgentsError

agent.ask(returns=...) did not get a well-formed answer, even after asking again, or agent.compact got an empty summary.

The last validation error is in __cause__.

NoHumanError

Bases: AlpineAgentsError

ask_human was called on an Agent with human=None.

MCPConnectionError

Bases: AlpineAgentsError

Could not connect to an MCP server, or the connection was lost. The original exception is in __cause__.

Errors the server reports for a tool call (isError) go to the model as the result instead.

ResumeWarning

ResumeWarning(message: str, changes: dict[str, tuple[Any, Any]])

Bases: UserWarning

The Agent resuming a saved State differs from the Agent that saved it.

A State holds the conversation, while the Agent's settings live in code. If the tools, model or system prompt changed between saving and resuming, the run still works but may behave differently: the model gets an error result when it calls a removed tool, and provider-specific blocks are not sent to a model of another provider. This may be what you want after a deploy, so it is a warning and not an error. Each loaded State is checked once, at its first run or arun. The system prompt is reported only as changed (history keeps its hash, not its text). Switching the model with agent.copy(model=...) between runs of a State that did not come from a store never warns. Python's default warnings filter shows the same message from the same line only once per process; a server that resumes many States should use catch_warnings or the "always" filter to see each one.

To refuse such a resume, turn it into an exception with warnings.filterwarnings("error", category=ResumeWarning). To show a notice in your UI, catch it with warnings.catch_warnings(record=True) and read .changes.

changes instance-attribute

changes = changes

What changed: {key: (saved_value, current_value)} for each differing key of the AgentInfo (name, model, system_sha256, tools, mcp_servers).

PermissionWarning

Bases: UserWarning

No permission in Agent(permissions=[...]) allowed or denied a tool call, so it was denied.

A call no permission decides about is never run. If that is what you want, turn the warning off with warnings.filterwarnings("ignore", category=PermissionWarning). To allow every call no permission denied, put AllowByDefault() at the end of the list.

ToolError

ToolError(message: str)

Bases: Exception

Raised by a tool for a failure the model should see and handle, such as a missing file or an HTTP 404.

The model gets the message as the call's error result, and the run continues. Any other exception from a tool stops the run, because it is usually a bug. To turn a library's exceptions into error results without catching them in every tool, use @tool(exception_handler=...).

Does not inherit from AlpineAgentsError: tools raise it, not alpineagents.

Example

@tool
def fetch_url(url: str) -> str:
    """Fetch a web page"""
    response = httpx.get(url)
    if response.status_code >= 400:
        raise ToolError(f"HTTP {response.status_code}: {url}")
    return response.text

Parameters:

Name	Type	Description	Default
message	str	What the model is told. Not empty.	required

Raises:

Type	Description
TypeError	message is not a string.
ValueError	message is empty or whitespace only.

ToolInputError

Bases: Exception

Raised by a tool when the arguments the model gave are wrong, such as a missing or invalid value.

The model gets (input error: {message}) as the call's result, and the run continues. @tool raises it for arguments that do not fit the type hints; a Tool subclass raises it from run for arguments it cannot use.

Example

def run(self, args: dict, state: State) -> str:
    if "title" not in args:
        raise ToolInputError("title is required")
    ...