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)
├── GatewayError                    (network / HTTP transport)
├── ConfigurationError              (bad init_assembly() arguments)
├── AdapterValidationError          (adapter ABC contract failure)
├── OpTerminatedError               (gateway terminated an in-flight op)
└── ToolExecutionBlockedError       (tool call blocked by policy)
    ├── MCPToolBlockedError         (MCP tool call blocked by policy)
    └── PolicyViolationError        (policy denied a tool call)

PolicyViolationError and MCPToolBlockedError both derive from ToolExecutionBlockedError, so except ToolExecutionBlockedError: catches every policy-blocked tool call regardless of which framework raised it.

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