Exceptions

All Agentix exceptions inherit from AgentixClientError. Import them directly from agentix.

from agentix import (
    AgentixClientError,
    AgentixConnectionError,
    AgentixResilienceError,
    ConfigurationError,
    AgentixInterruptedError,
    AgentixAgentNotFoundError,
    AgentixTimeoutError,
    AgentixToolDefinitionError,
    AgentixHookError,
    ProcessError,
    ToolError,
    ToolTimeoutError,
    ToolPermissionError,
    SandboxViolationError,
)

Exception hierarchy

AgentixClientError
├── AgentixConnectionError      — LLM API connection failed
├── AgentixResilienceError      — Circuit breaker is open
├── ConfigurationError          — Invalid AgentixAgentOptions
├── AgentixInterruptedError     — client.interrupt() was called, or hard deny
├── AgentixAgentNotFoundError   — Sub-agent not found in agents dict
├── AgentixTimeoutError         — Agent or LLM call timed out
├── AgentixToolDefinitionError  — Invalid tool registration
├── AgentixHookError            — Hook callback raised an exception
├── ProcessError                — Subprocess execution failed
└── ToolError
    ├── ToolTimeoutError        — Tool exceeded tool_timeout
    ├── ToolPermissionError     — Tool was denied by permission system
    └── SandboxViolationError   — Tool attempted to access outside sandbox

Common patterns

from agentix import AgentixClientError, AgentixResilienceError, ConfigurationError

async def run(client, prompt):
    try:
        async for msg in client.query(prompt):
            if isinstance(msg, ResultMessage):
                return msg.result
    except AgentixResilienceError as e:
        print(f"Circuit breaker open: {e}")
        raise
    except AgentixInterruptedError:
        print("Query was interrupted")
        return None
    except AgentixClientError as e:
        print(f"Agent error: {e}")
        raise

ConfigurationError

Raised at AgentixAgentOptions construction time for invalid configurations:

from agentix import AgentixAgentOptions, ConfigurationError

try:
    options = AgentixAgentOptions(
        continue_conversation=True,
        fork_session=True,  # ← cannot both be True
    )
except ConfigurationError as e:
    print(e)

AgentixResilienceError

Raised when the circuit breaker is open (too many consecutive failures). The circuit resets after circuit_breaker_cooldown seconds.

from agentix import AgentixResilienceError

try:
    async for msg in client.query("..."): ...
except AgentixResilienceError:
    # Back off and retry later
    await asyncio.sleep(60)

SandboxViolationError

Raised when a tool attempts to access a path outside the configured sandbox workspace:

from agentix import SandboxViolationError

try:
    async for msg in client.query("Read /etc/passwd"): ...
except SandboxViolationError as e:
    print(f"Sandbox violation: {e}")