Errors

The errors the SDK raises, with their bases. except agents.AgentsError catches every failure a stable call raises, from the SDK or from where the agent runs. Argument errors stay ValueError or TypeError, and a cancelled call raises asyncio.CancelledError.

Reusing an idempotency_key= with other options raises SessionIdempotencyConflictError. Sending to a subagent's session raises an agents.UnsupportedSessionProcedureError.

class AgentsError(Exception)

class AgentsError(Exception)

The base of the errors the SDK raises.

except agents.AgentsError catches a failed session or turn call for local and deployed sessions, including an HTTP error (APIStatusError), a connection error (APIConnectionError) or an error the session reported, such as SessionBusyError. Argument errors stay ValueError or TypeError, and a cancelled call raises asyncio.CancelledError.

class SdkError(AgentsError, ValueError)

class SdkError(AgentsError, ValueError)

A call the SDK refuses, such as one with a wrong argument value or one on a local runtime that has closed.

class SessionNotFoundError(AgentsError, LookupError)

class SessionNotFoundError(AgentsError, LookupError)

A call named a session that does not exist, or that you cannot read.

For a deployed agent, either no session has this ID, or the API key in use belongs to a workspace that cannot read it. For a local session, no session with this ID ran in this process, or an agents.local_runtime() block freed it and the event loop no longer remembers it: each loop remembers the newest 10,000. In both cases, scope="tree" of list_sessions also raises it for a subagent as the root.

class TurnNotFoundError(AgentsError, LookupError)

class TurnNotFoundError(AgentsError, LookupError)

A turn handle named a turn its session does not have.

class InvalidCursorError(SdkError)

class InvalidCursorError(SdkError)

after= is not a position of the session it reads.

The cursor is not one the session gave, or it is a cursor or a record of another session. A record or a cursor of another session raises before any read, on iter_events() too. A cursor the session never gave raises when the session reads it: at the first iteration of iter_events(), or while the turn runs for result(). cursor is the cursor passed, a record's cursor for a record. A cursor saved by SDK 1.0 is accepted; the error shows it with this session's ID.

A program that stores cursors can catch it and read again without one:

try:
    state = await turn.result(after=stored_cursor)
except agents.InvalidCursorError:
    state = await turn.result()

try:
    state = await turn.result(after=stored_cursor)
except agents.InvalidCursorError:
    state = await turn.result()

class ObservationLost(AgentsError, RuntimeError)

class ObservationLost(AgentsError, RuntimeError)

The session's events, or the open callbacks of its subagents, could not be read again after the connection was lost, or the events' stream ended.

Nothing was stopped: the session keeps running. cursor is the position up to which the events were given, or None when none was; continue reading after it: no event is missed.

class OutcomeUnknownError(AgentsError, RuntimeError)

class OutcomeUnknownError(AgentsError, RuntimeError)

The SDK could not confirm in time whether the session started or the request applied.

idempotency_key is the key to retry with, including one the SDK generated, or the callback ID for a callback answer. It is None for an operation without a key, and for a start_turn that found another turn running on an agent deployed with an older SDK: that key would be refused again. Start again with idempotency_key=None, and the SDK makes a new key.

class SessionStartupTimeoutError(OutcomeUnknownError)

class SessionStartupTimeoutError(OutcomeUnknownError)

The session was created, but it was not ready before the deadline.

The session is not cancelled. Use agent.session(session_id) (or Agent.load_from(agent_name=...).session(session_id) elsewhere) to attach again without starting another session.

class SessionBusyError(AgentsError, RuntimeError)

class SessionBusyError(AgentsError, RuntimeError)

The session cannot take the message now, and nothing was applied.

It is raised after the request was retried for a while. Retry the same request later.

class SessionConfigMismatchError(AgentsError, RuntimeError)

class SessionConfigMismatchError(AgentsError, RuntimeError)

The agent that continues a saved local session is not the agent that started it.

A saved session continues only with the same model, instructions, tools and other settings it was saved with. Continue it with that agent, or start a new session.

class SessionInUseError(AgentsError, RuntimeError)

class SessionInUseError(AgentsError, RuntimeError)

Another process has this saved local session open, so this one cannot continue it.

Saved local sessions (journal_factory= of agents.local_runtime()) take a lock on their journal while a process has them open. Retry once the other process has left its agents.local_runtime() block or exited.

class SessionTerminatedError(AgentsError, RuntimeError)

class SessionTerminatedError(AgentsError, RuntimeError)

The session is closed or has ended, and takes no more calls.

class SessionIdempotencyConflictError(AgentsError, RuntimeError)

class SessionIdempotencyConflictError(AgentsError, RuntimeError)

An idempotency key was reused for a different request, or the requests cannot be compared.

They cannot be compared when the first request is too old, or when a local call was cancelled after it applied the message but before it recorded the key. In both cases the key's first request was applied, so do not send that message again with a new key. This call applied nothing. Use a new key for a new request.

class LegacySessionError(UnsupportedAgentFeatureError)

class LegacySessionError(UnsupportedAgentFeatureError)

This session was created by an older version of the platform, and this SDK cannot open it.

Every session that agents.Agent starts can be opened. This SDK cannot read, follow or send to an older one: start a new session.

class RemoteAgentDeploymentNotFoundError(AgentsError, RuntimeError)

class RemoteAgentDeploymentNotFoundError(AgentsError, RuntimeError)

The deployed agent behind this handle no longer exists, for example after a shutdown.

class APIStatusError(AgentsError, httpx.HTTPStatusError)

class APIStatusError(AgentsError, httpx.HTTPStatusError)

Mistral answered an HTTP request with an error status.

class AuthenticationError(APIStatusError)

class AuthenticationError(APIStatusError)

Mistral refused the API key: HTTP 401.

class PermissionDeniedError(APIStatusError)

class PermissionDeniedError(APIStatusError)

The API key may not do this: HTTP 403.

class RateLimitError(APIStatusError)

class RateLimitError(APIStatusError)

Too many requests: HTTP 429. The same request may succeed later.

retry_after is the wait in seconds the server named, or None when it named none, for example for a concurrent session limit. A session start already waits out a Retry-After that ends within 30 seconds of the start before it raises this error.

class InternalServerError(APIStatusError)

class InternalServerError(APIStatusError)

Mistral failed: HTTP 500 or above.

class APIConnectionError(AgentsError, httpx.TransportError)

class APIConnectionError(AgentsError, httpx.TransportError)

An HTTP request got no answer: the connection failed, or the network dropped it.

It is also an instance of the httpx class that failed, such as httpx.ConnectError. It is not a builtin ConnectionError.

class APITimeoutError(APIConnectionError, httpx.TimeoutException)

class APITimeoutError(APIConnectionError, httpx.TimeoutException)

An HTTP request timed out. It is not a builtin TimeoutError.

class UnsupportedAgentFeatureError(SdkError, RuntimeError)

class UnsupportedAgentFeatureError(SdkError, RuntimeError)

Where the agent runs does not support this Agents SDK feature.

class UnsupportedSessionProcedureError(AgentsError, RuntimeError)

class UnsupportedSessionProcedureError(AgentsError, RuntimeError)

Where the session runs does not support this call, and nothing was sent.

class ClientToolAnswerError(AgentsError, RuntimeError)

class ClientToolAnswerError(AgentsError, RuntimeError)

A client tool answer ran, but sending it to the session failed.

callback_id, session_id and turn_id name the call: a subagent's call has the subagent's session and turn. The send error is the __cause__. The turn keeps running, and the call fails at its callback timeout: the model gets a tool error. To follow the turn, use agent.session(session_id).turn(turn_id).

class MistralConnectorNotFoundError(AgentsError, LookupError)

class MistralConnectorNotFoundError(AgentsError, LookupError)

A connector name that matches no connector the user who runs the session can see.

No name in connectors= raises it: the session starts without that connector and sends an agents.Notice, whose details["connector"] is the name and details["reason"] names the close matches. connector_name is the name, and close_matches the names of visible connectors close to it.