Skip to content

Types & Exceptions

Enums

AutonomyLevel

Bases: StrEnum

Agent autonomy levels.

Source code in src/agenticapi/types.py 
15
16
17
18
19
20
class AutonomyLevel(StrEnum):
    """Agent autonomy levels."""

    AUTO = "auto"
    SUPERVISED = "supervised"
    MANUAL = "manual"

Severity

Bases: StrEnum

Severity levels for incidents and alerts.

Source code in src/agenticapi/types.py 
32
33
34
35
36
37
38
class Severity(StrEnum):
    """Severity levels for incidents and alerts."""

    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

TraceLevel

Bases: StrEnum

Audit trace levels.

Source code in src/agenticapi/types.py 
23
24
25
26
27
28
29
class TraceLevel(StrEnum):
    """Audit trace levels."""

    MINIMAL = "minimal"
    STANDARD = "standard"
    FULL = "full"
    DEBUG = "debug"

Exception Hierarchy

AgenticAPIError

Bases: Exception

Base exception for all AgenticAPI errors.

Source code in src/agenticapi/exceptions.py 
10
11
class AgenticAPIError(Exception):
    """Base exception for all AgenticAPI errors."""

Harness Exceptions

HarnessError

Bases: AgenticAPIError

Base exception for harness engine errors.

Source code in src/agenticapi/exceptions.py 
17
18
class HarnessError(AgenticAPIError):
    """Base exception for harness engine errors."""

PolicyViolation

Bases: HarnessError

Policy violation. Generated code does not conform to policy.

Source code in src/agenticapi/exceptions.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
class PolicyViolation(HarnessError):
    """Policy violation. Generated code does not conform to policy."""

    def __init__(
        self,
        policy: str,
        violation: str,
        generated_code: str | None = None,
    ) -> None:
        self.policy = policy
        self.violation = violation
        self.generated_code = generated_code
        super().__init__(f"Policy '{policy}' violated: {violation}")

SandboxViolation

Bases: HarnessError

Sandbox violation. Forbidden operation detected at runtime.

Source code in src/agenticapi/exceptions.py 
70
71
class SandboxViolation(HarnessError):
    """Sandbox violation. Forbidden operation detected at runtime."""

ApprovalRequired

Bases: HarnessError

Approval required. Human approval is needed to continue.

Source code in src/agenticapi/exceptions.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
class ApprovalRequired(HarnessError):
    """Approval required. Human approval is needed to continue."""

    def __init__(
        self,
        message: str = "Approval required",
        *,
        request_id: str | None = None,
        approvers: list[str] | None = None,
    ) -> None:
        self.request_id = request_id
        self.approvers = approvers or []
        super().__init__(message)

ApprovalDenied

Bases: HarnessError

Approval was denied.

Source code in src/agenticapi/exceptions.py 
89
90
class ApprovalDenied(HarnessError):
    """Approval was denied."""

ApprovalTimeout

Bases: HarnessError

Approval timed out.

Source code in src/agenticapi/exceptions.py 
93
94
class ApprovalTimeout(HarnessError):
    """Approval timed out."""

Runtime Exceptions

AgentRuntimeError

Bases: AgenticAPIError

Base exception for agent runtime errors.

Source code in src/agenticapi/exceptions.py 
100
101
class AgentRuntimeError(AgenticAPIError):
    """Base exception for agent runtime errors."""

CodeGenerationError

Bases: AgentRuntimeError

Code generation failed.

Source code in src/agenticapi/exceptions.py 
104
105
class CodeGenerationError(AgentRuntimeError):
    """Code generation failed."""

CodeExecutionError

Bases: AgentRuntimeError

Generated code execution failed.

Source code in src/agenticapi/exceptions.py 
108
109
class CodeExecutionError(AgentRuntimeError):
    """Generated code execution failed."""

ToolError

Bases: AgentRuntimeError

Tool invocation failed.

Source code in src/agenticapi/exceptions.py 
112
113
class ToolError(AgentRuntimeError):
    """Tool invocation failed."""

ContextError

Bases: AgentRuntimeError

Context construction failed.

Source code in src/agenticapi/exceptions.py 
116
117
class ContextError(AgentRuntimeError):
    """Context construction failed."""

Interface Exceptions

InterfaceError

Bases: AgenticAPIError

Base exception for interface layer errors.

Source code in src/agenticapi/exceptions.py 
123
124
class InterfaceError(AgenticAPIError):
    """Base exception for interface layer errors."""

IntentParseError

Bases: InterfaceError

Intent parsing failed.

Source code in src/agenticapi/exceptions.py 
127
128
class IntentParseError(InterfaceError):
    """Intent parsing failed."""

SessionError

Bases: InterfaceError

Session management error.

Source code in src/agenticapi/exceptions.py 
131
132
class SessionError(InterfaceError):
    """Session management error."""

A2AError

Bases: InterfaceError

Agent-to-Agent communication error.

Source code in src/agenticapi/exceptions.py 
135
136
class A2AError(InterfaceError):
    """Agent-to-Agent communication error."""

AuthenticationError

Bases: InterfaceError

Authentication failed or credentials missing.

Source code in src/agenticapi/exceptions.py 
139
140
class AuthenticationError(InterfaceError):
    """Authentication failed or credentials missing."""

AuthorizationError

Bases: InterfaceError

Authenticated user lacks required permissions.

Source code in src/agenticapi/exceptions.py 
143
144
class AuthorizationError(InterfaceError):
    """Authenticated user lacks required permissions."""

HTTP Status Mapping

Exception HTTP Status
IntentParseError 400 Bad Request
SessionError 400 Bad Request
AuthenticationError 401 Unauthorized
PolicyViolation 403 Forbidden
ApprovalDenied 403 Forbidden
SandboxViolation 403 Forbidden
AuthorizationError 403 Forbidden
ApprovalRequired 202 Accepted
ApprovalTimeout 408 Request Timeout
CodeGenerationError 500 Internal Server Error
CodeExecutionError 500 Internal Server Error
ToolError 502 Bad Gateway
A2AError 502 Bad Gateway

Dependency Injection

HarnessDepends

Dependency injection marker for harness components.

Analogous to FastAPI's Depends(). Marks a parameter as requiring injection of a harness-related dependency at runtime.

Example

@app.agent_endpoint(name="users") async def user_agent( intent: Intent, context: AgentContext, harness: HarnessEngine = HarnessDepends(get_harness), ): ...

Source code in src/agenticapi/params.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class HarnessDepends:
    """Dependency injection marker for harness components.

    Analogous to FastAPI's Depends(). Marks a parameter as requiring
    injection of a harness-related dependency at runtime.

    Example:
        @app.agent_endpoint(name="users")
        async def user_agent(
            intent: Intent,
            context: AgentContext,
            harness: HarnessEngine = HarnessDepends(get_harness),
        ):
            ...
    """

    def __init__(self, dependency: Callable[..., Any]) -> None:
        """Initialize the dependency marker.

        Args:
            dependency: A callable that provides the dependency value.
        """
        self.dependency = dependency

    def __repr__(self) -> str:
        return f"HarnessDepends({self.dependency!r})"

__init__ 

__init__(dependency: Callable[..., Any]) -> None

Initialize the dependency marker.

Parameters:

Name Type Description Default
dependency Callable[..., Any]

A callable that provides the dependency value.

 required
Source code in src/agenticapi/params.py 
31
32
33
34
35
36
37
def __init__(self, dependency: Callable[..., Any]) -> None:
    """Initialize the dependency marker.

    Args:
        dependency: A callable that provides the dependency value.
    """
    self.dependency = dependency