Skip to content

agentix.events

events

Observability hooks.

AgentEvents is a bundle of optional callbacks the loop fires as it runs — for tracing, logging, and the audit trail the governance story promises. Every callback may be sync or async; the loop awaits awaitable results. Unset callbacks are simply skipped.

AgentOutcome dataclass 

AgentOutcome(
    status: str,
    answer: str | None = None,
    parsed: Any = None,
    reason: str | None = None,
    steps: int = 0,
    tokens_used: int = 0,
    cost_usd: float = 0.0,
    transcript: list[Message] = list(),
    pending: list[PendingApproval] = list(),
)

Terminal (or suspended) result of an agent run.

Message dataclass 

Message(
    role: Role,
    content: str | list[ContentPart],
    trusted: bool = False,
    name: str | None = None,
    meta: dict[str, Any] = dict(),
)

A single conversation message.

content is either a plain str (the common case) or a list of :class:~agentix.content.ContentPart for multimodal input (text interleaved with images / documents / audio). Use :attr:text for a string view that works regardless.

trusted marks whether the content originated from the real user (an instruction source) rather than from tool output (data to reason about, never instructions to follow). The loop sets this; guards and the security subsystem rely on it.

text property 

text: str

The textual content: the string itself, or the concatenation of the :class:~agentix.content.TextPart parts (media parts contribute nothing).

ModelResponse dataclass 

ModelResponse(
    text: str = "",
    tool_calls: list[ToolCall] = list(),
    tokens_used: int = 0,
    input_tokens: int = 0,
    output_tokens: int = 0,
    cost_usd: float = 0.0,
)

What a model adapter returns each turn.

A response carries assistant text and/or one or more tool_calls. When there are no tool calls the turn is final.

ToolCall dataclass 

ToolCall(
    name: str,
    args: dict[str, Any] = dict(),
    id: str | None = None,
)

A tool invocation requested by the model.

AgentEvents dataclass 

AgentEvents(
    on_model: _Cb = None,
    on_tool_call: _Cb = None,
    on_guard_decision: _Cb = None,
    on_confirm: _Cb = None,
    on_tool_result: _Cb = None,
    on_compact: _Cb = None,
    on_suspend: _Cb = None,
    on_final: _Cb = None,
)

Optional lifecycle callbacks. Wire only the ones you need.