Exceptions

The SDK raises a small, focused exception hierarchy rooted at AssemblyError. Every error you can catch from agent_assembly is a subclass of AssemblyError — code that does except AssemblyError: will catch any SDK-raised error without needing to enumerate the leaf classes.

Hierarchy at a glance

AssemblyError                       (base)
├── AgentError                      (agent registration / lifecycle)
├── PolicyError                     (policy evaluation problems)
│   └── PolicyViolationError        (policy denied an action)
├── GatewayError                    (network / HTTP transport)
├── ConfigurationError              (bad init_assembly() arguments)
├── AdapterValidationError          (adapter ABC contract failure)
├── ToolExecutionBlockedError       (tool call blocked by policy)
└── MCPToolBlockedError             (MCP tool call blocked by policy)

PolicyTimeoutError is also raised by the optional native runtime client (agent_assembly._core) when a policy check exceeds its deadline; it is not a subclass of AssemblyError because it originates from the Rust FFI layer. Catch it explicitly if you opt into the native fast path.

agent_assembly.exceptions

Exception hierarchy for SDK errors.

AssemblyError

Bases: Exception

Base exception for Agent Assembly SDK errors.

AgentError

Bases: AssemblyError

Exception raised for agent-related errors.

PolicyError

Bases: AssemblyError

Exception raised for policy-related errors.

GatewayError

Bases: AssemblyError

Exception raised for gateway communication errors.

ConfigurationError

Bases: AssemblyError

Exception raised for configuration errors.

AdapterValidationError

Bases: AssemblyError

Exception raised when an adapter contract is invalid.

ToolExecutionBlockedError

Bases: AssemblyError

Exception raised when a tool run is blocked by governance.

MCPToolBlockedError

MCPToolBlockedError(
    message: str,
    *,
    tool_name: str | None = None,
    server: str | None = None,
)

Bases: ToolExecutionBlockedError

Exception raised when an MCP tool call is blocked by governance.

Source code in agent_assembly/exceptions/__init__.py

def __init__(
    self,
    message: str,
    *,
    tool_name: str | None = None,
    server: str | None = None,
) -> None:
    super().__init__(message)
    self.tool_name = tool_name
    self.server = server

PolicyViolationError

Bases: ToolExecutionBlockedError

Exception raised when policy blocks tool execution.

OpTerminatedError

OpTerminatedError(message: str, *, op_id: str)

Bases: AssemblyError

Raised when the gateway terminates an in-flight op (AAASM-1422 PR-E).

Carries the originating op_id so callers can correlate the failure against the operation they were awaiting. Surfaced by OpControlSubscriber.await_op when an OP_CONTROL_SIGNAL_TERMINATE arrives for the awaited op.

Source code in agent_assembly/exceptions/__init__.py

def __init__(self, message: str, *, op_id: str) -> None:
    super().__init__(message)
    self.op_id = op_id