Errors

All Pilota runtime errors inherit from AgentError.

Error	Meaning	Typical response
ConfigurationError	The requested execution cannot be configured safely	Fix caller input
ProviderError	The provider request or response failed	Retry, fail over, or surface
ModelLimitError	A model-call or tool-call limit was exhausted	Increase budget or narrow task
ToolError	A tool could not complete an operation	Inspect tool input or implementation
ToolTimeoutError	A tool exceeded its own timeout	Tune command or timeout
PermissionDenied	An operation exceeded granted authority	Change policy only if intended
ResultContractError	Final values exhausted validation retries	Improve task/schema or handle failure
ExecutionCancelled	The caller cancelled at an execution boundary	Preserve evidence and stop

Shared evidence

AgentError exposes:

error.execution_id  # str | None
error.artifacts     # tuple[str, ...]
error.trace         # Trace | None

Evidence is attached when an error occurs during an active execution. A configuration error raised while constructing a provider directly may not have an execution ID.

Tool errors inside the loop

PermissionDenied, ToolError, and unexpected exceptions raised by tools normally become model observations rather than escaping immediately. This gives the model a chance to recover.

The exception can still escape when:

• application code invokes a tool directly,
• configuration fails before invocation,
• execution ends later because a limit is exhausted.

API definitions

pilota.errors.AgentError

AgentError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

Base class for execution failures.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

Attributes

execution_id instance-attribute

execution_id = execution_id

artifacts instance-attribute

artifacts = tuple(artifacts)

trace instance-attribute

trace = trace

Methods:

pilota.errors.ConfigurationError

ConfigurationError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

The requested execution cannot be configured safely.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ProviderError

ProviderError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

A model provider failed.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ModelLimitError

ModelLimitError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

An execution exhausted a model or tool-call limit.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ToolError

ToolError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

A tool failed while executing.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ToolTimeoutError

ToolTimeoutError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

A tool exceeded its configured timeout.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.PermissionDenied

PermissionDenied(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

A requested operation was outside the granted authority.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ResultContractError

ResultContractError(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

A final model result did not satisfy the requested Python type.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace

pilota.errors.ExecutionCancelled

ExecutionCancelled(message: str, *, execution_id: str | None = None, artifacts: Sequence[str] = (), trace: Trace | None = None)

The caller cancelled execution.

Source code in src/pilota/errors.py

def __init__(
    self,
    message: str,
    *,
    execution_id: str | None = None,
    artifacts: Sequence[str] = (),
    trace: Trace | None = None,
) -> None:
    super().__init__(message)
    self.execution_id = execution_id
    self.artifacts = tuple(artifacts)
    self.trace = trace