Skip to content

agentix.types

types

Core data types shared across the agent loop.

These are plain, framework-agnostic dataclasses. Provider adapters translate between these and a vendor's wire format; the loop only ever sees these.

Role

Bases: str, Enum

Author of a conversation message.

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).

ToolCall dataclass 

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

A tool invocation requested by the model.

ToolResult dataclass 

ToolResult(
    name: str,
    content: str,
    call_id: str | None = None,
    ok: bool = True,
    cost_usd: float = 0.0,
    tokens_used: int = 0,
)

The outcome of executing a single :class:ToolCall.

A tool may report cost_usd / tokens_used (e.g. a subagent rolling up its child run's spend) — the loop adds these into the parent run's totals.

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.

PendingApproval dataclass 

PendingApproval(call: ToolCall, reason: str = '')

A tool call paused awaiting a human decision (status == "suspended").

Returned on :attr:AgentOutcome.pending; approve or deny it by passing {call.id: True/False} to :meth:~agentix.Agent.resume.

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.