Agent Air employs a strongly-typed, hierarchical error handling strategy designed to provide both developer clarity and resilient runtime behavior.

Philosophy

  1. Explicitness: Errors are part of the type signature (Result<T, E>). We avoid panics for recoverable conditions.
  2. Hierarchy: A top-level AgentError unifies domain-specific errors (ControllerError, LlmError, etc.), allowing unified handling at the application boundary.
  3. Context: Errors carry context (e.g., which file failed to load, which provider rejected the key) to aid debugging.
  4. User-Facing vs. Internal: We distinguish between errors that should be shown to the user (e.g., “API key invalid”) and those that are internal system faults (e.g., “Channel closed unexpectedly”).

The Error Hierarchy

The root of the hierarchy is AgentError, which serves as the “umbrella” type for the entire crate.

AgentError
├── ConfigError
│   ├── ParseError
│   └── IoError
├── ControllerError
│   ├── ContextLimitExceeded
│   └── ToolExecutionFailed
├── LlmError
│   ├── ProviderError
│   └── NetworkError
└── ToolError

Library Support

We utilize thiserror for ergonomic error definition and anyhow for applications where precise error handling is less critical than capturing the failure chain.