API Reference¶

An Agent whose config comes from class attributes instead of init args.

usage accumulates token usage across every run/run_sync/run_streamed call made on this instance; last_usage holds just the most recent call's usage. Both are read from RunContext.usage, which the turn loop populates regardless of hooks.

One run is bounded three ways, each None/unset meaning "no ceiling of that kind": max_turns (model calls, default 10), max_tokens (total tokens the run may spend), and timeout (wall-clock seconds). Hitting any of them ends the run as Run(status="error"), the same as every other RunaError. max_tokens is the run's whole budget and is not the same knob as ModelSettings(max_tokens=...), which caps one response's length.

An instance carries per-run state (history, usage), so it is not safe to share across concurrent runs; see run for the rule and the two ways to satisfy it.

Build config from class attributes and wire up any subagents and guardrails.

These parameters are the closed set of settings (_AGENT_FIELDS is read off this signature): each one can be declared on the subclass or passed here, the argument winning, and an unset one falls back to the class attribute of the same name -- in one pass over that tuple (_settings), so adding one here resolves it. A name that is neither is a TypeError from this signature, and a UserError naming the setting it probably meant when it is declared in a class body instead (see _reject_unknown_settings).

mcp lists the agent's MCP servers; self.mcp_servers is what it resolved to.

memory opts this agent into long-term memory, one of: - "auto" (or a Memory(...) instance, or any object shaped like runa.memory's MemoryLike): the turn loop retrieves relevant memories before each run and persists new ones after -- no manual memory.search/.remember calls. - "llm": the model gets a search_memory tool and decides itself when to call it; no automatic retrieval/persistence. - None (the default): the agent behaves exactly as if runa.memory didn't exist. "llm" always uses a default Memory(); pass your own instance for "auto" mode if you need a non-default db_path/model/store -- or a wholesale custom MemoryLike object to replace embeddings-based retrieval entirely, not just its storage backend.

knowledge opts this agent into retrieval from application/domain documents, one of "auto", "llm", a Knowledge(...) (or KnowledgeLike-shaped) instance, or None (the default) -- the same four shapes as memory, with the same meaning: "auto"/an instance searches automatically before every turn (no tools=[...] wiring needed); "llm" gives the model a search_knowledge tool it calls itself; None leaves the agent unaffected. "llm" always uses a default Knowledge(); pass your own instance for "auto" mode if you need a non-default directory/db_path/model/store, or a custom KnowledgeLike object for a retrieval pipeline of your own.

compact keeps history/session from growing without bound, one of: - True: runa.compact.default_compactor -- past DEFAULT_COMPACTION_TOKENS, keep only the most recent exchange. A rolling window, not a summary. - a runa.compact.Compactor (any (items, usage_tokens) -> items | None callable): your own strategy -- a different threshold, an LLM summary, whatever you return. - False (the default): off. Resolved to a Compactor (or None) here, as self.compactor, the way memory=/ knowledge= are; anything else is a UserError at construction.

max_turns caps how many model calls one run may make before MaxTurnsExceeded; max_tokens caps the tokens they may spend before MaxTokensExceeded; timeout caps the run's wall-clock seconds before RunTimeout. All three are optional ceilings, and all three end the run as Run(status="error").

Methods:

Attributes:

graph: Digraph

as_tool(
    tool_name: str | None, tool_description: str | None
) -> FunctionTool

run(
    message: MessageContent | RunState,
    context: Any = None,
    hooks: Hooks[Any] | None = None,
    session: Session | str | None = None,
) -> Run

run_sync(
    message: MessageContent | RunState,
    context: Any = None,
    hooks: Hooks[Any] | None = None,
    session: Session | str | None = None,
) -> Run

run_streamed(
    message: MessageContent | RunState,
    context: Any = None,
    hooks: Hooks[Any] | None = None,
    session: Session | str | None = None,
) -> RunStream

evaluate(
    dataset: Iterable[Case],
    *,
    judge: str | None = None,
    threshold: float | None = None,
    thresholds: dict[str, float] | None = None,
    concurrency: int = 8,
) -> Report

Bases: Protocol

Every attribute Runa reads off an agent: the other side of the seam, as types.

Attributes:

name: str

instructions: str | Callable[..., Any] | None

model: str | Model

model_settings: ModelSettings

tools: list[FunctionTool]

mcp_servers: list[Any]

handoffs: list[Any]

bound_guardrails: dict[Phase, list[BoundGuardrail]]

output_type: type | None

memory: Any

knowledge: Any

compactor: Compactor | None

hooks: Hooks[Any] | None

A tool the model can call: its schema, and the callable that actually runs it.

Attributes:

on_invoke_tool: Callable[
    [RunContext, _Governance, str, str], Awaitable[Any]
]

guardrails: dict[Phase, list[BoundGuardrail]] = field(
    default_factory=dict
)

delegate: Any = None

A predicate bound to neither side yet; .input/.output (or .i/.o) picks which.

@guardrail wraps a plain (value) -> bool predicate (tripping the guardrail on True) into this, the same way @tool wraps a plain function into a FunctionTool. Read .input to bind it to the input side, .output for the output side; .i/.o are the exact same binding under a shorter name, there is no third spelling. The same bound object works in both places it's listed:

• In an Agent.guardrails list, it's bound to Phase.INPUT/Phase.OUTPUT: the predicate sees the latest user message as plain text (regardless of whether the run was passed a string or the running list of input items) on .input, or the agent's final output on .output.
• In a @tool(guardrails=[...]) list, the same object is rebound to Phase.TOOL_INPUT/ Phase.TOOL_OUTPUT: the predicate sees the tool call's arguments (parsed from JSON into a dict) on .input, or the tool's raw return value on .output.

The predicate's docstring becomes output_info. Listed bare (no .input/.output), it's wired as both sides of whichever pair applies.

Store the predicate to bind on .input/.output access.

Attributes:

input: BoundGuardrail

output: BoundGuardrail

i: BoundGuardrail

o: BoundGuardrail

Bases: StrEnum

Where a guardrail runs: agent-or-tool by input-or-output, the 2x2 named once.

The phase decides everything the four used to spell out separately: which list an entry belongs to, what the one value its function is handed means (the agent's own input or final output, a tool call's arguments or return value), which key its results are recorded under, and how a tripwire names it.

Attributes:

on_tool: bool

on_output: bool

title: str

What a guardrail function returns: the predicate's docstring, plus trip/no-trip.

output_info is the @guardrail predicate's __doc__ (or None), never anything it computed: a predicate returns a bool, so what it checks for is all the audit trail can say.

One shape for all four phases, because tripped is the only question anyone asks a verdict. Whether the guardrail watched an agent's turn or one tool call is Phase's to say -- the wrapper reads phase to know what the one value it was handed is, GuardrailResult.phase records it for the audit trail -- so the verdict doesn't re-encode it as a second type.

A guardrail plus the verdict it returned and the Phase it returned it in.

Every guardrail run this run is recorded (see GuardrailResults), not just the one that stopped the run; tripped distinguishes the two.

A run's guardrail audit trail: every GuardrailResult it produced, keyed by Phase.

One mapping rather than a list per phase, so the four names RUNA.md documents are written once, on GuardrailAudit, and a phase nothing ran in simply has no key.

Methods:

record(result: GuardrailResult) -> None

__getitem__(phase: Phase) -> list[GuardrailResult]

snapshot() -> GuardrailResults

Bases: Session

Conversation history for one session_id, persisted to the local db/runa.db.

Every method here is _off_loop: a plain synchronous body, handed to a worker thread to satisfy Session's async def. Each opens its own short-lived connection, so no sqlite3 object is ever touched from two threads.

Store session_id and where in runa.db its history lives.

db_path defaults to runa.db.sqlite_path(), so this history lands in the same local file as every other concern's -- including when RUNA_DATABASE_URL relocates it. Pass one to point at some other file.

user_id scopes this session's automatic memory, if its agent has any; see Session.

Methods:

get_items(
    limit: int | None = None,
) -> list[ConversationItem]

add_items(items: list[ConversationItem]) -> None

set_items(items: list[ConversationItem]) -> None

pop_item() -> ConversationItem | None

clear_session() -> None

Bases: ABC

What run_internal needs to persist and replay conversation history across turns.

A base class, where the read side (SessionStore) and Cache are protocols a backend satisfies by shape alone: inheritance is what lets set_items below hand a default implementation out, so a custom backend writes four methods and gets Agent(compact=...) without a fifth.

user_id is optional and unrelated to history: run_internal reads it (when set) to scope automatic Agent.memory retrieval/persistence to one user, so app code doesn't have to thread a user_id through Memory.remember/.search itself. None means memory that goes through this session lands in its own user-less scope, not everyone's.

Methods:

get_items(
    limit: int | None = None,
) -> list[ConversationItem]

add_items(items: list[ConversationItem]) -> None

pop_item() -> ConversationItem | None

clear_session() -> None

set_items(items: list[ConversationItem]) -> None

Durable semantic facts, scoped by user_id: remember/search/forget, nothing lower.

Memory() means OpenAI's text-embedding-3-small over whichever database runa.db resolves: embeddings and vector storage are entirely internal, so callers only ever see text in and MemoryMatches out. store= swaps that for a custom MemoryStore, unrelated to embeddings.

Configure the embedding model and, unless store is given, this deployment's store.

dimensions only needs setting for a model not in Runa's built-in size table.

Methods:

remember(
    text: str,
    *,
    user_id: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> int

search(
    query: str, *, user_id: str | None = None, k: int = 5
) -> list[MemoryMatch]

forget(
    memory_id: int, *, user_id: str | None = None
) -> None

remember_from_conversation(
    conversation: str, *, user_id: str | None, model: Any
) -> list[str]

One Memory.search result: its id, stored text, metadata, and distance to the query.

Application/domain documents, retrieved by meaning: search/ingest, nothing lower.

Knowledge() means app/knowledge/, OpenAI's text-embedding-3-small, and whichever database runa.db resolves: discovery, chunking, embeddings and vector storage are entirely internal, so callers only ever see a source directory in and KnowledgeMatches out. Attach an instance to Agent(knowledge=...) and run/run_sync search it automatically before every turn; no tools=[...] wiring needed.

Configure the source directory, embedding model, and, unless store is given, storage.

dimensions only needs setting for a model not in Runa's built-in size table.

A relative directory is resolved against the project runa.project.use named, the same way the store's own file is, so an app served from outside its own directory reads its corpus and writes its vectors in one place. Absolute paths are left alone, which is how app code that means a directory somewhere else says so.

Methods:

ingest() -> int

search(query: str, *, k: int = 5) -> list[KnowledgeMatch]

One Knowledge.search result: its id, stored text, source file, and distance.

Bases: Protocol

What application code needs from a cache: get/set/delete/clear, nothing lower.

No inheritance required, every backend satisfies this by matching shape, the same escape hatch as MemoryStore/SessionStore's custom-backend story. The two local backends expire entries lazily: an expired key is only evicted (and reported as a miss) the next time get looks it up, not by a background sweep.

Methods:

get(key: str) -> Any

set(key: str, value: Any, ttl: float | None = None) -> None

delete(key: str) -> None

clear() -> None

In-process Cache: a plain dict, gone when the process exits.

Start empty.

Methods:

get(key: str) -> Any

set(key: str, value: Any, ttl: float | None = None) -> None

delete(key: str) -> None

clear() -> None

Persistent Cache: the cache_entries table inside db/runa.db, surviving restarts.

Store where this cache's table lives, defaulting to db.sqlite_path().

The table is created on first use.

Methods:

get(key: str) -> Any

set(key: str, value: Any, ttl: float | None = None) -> None

delete(key: str) -> None

clear() -> None

The one way to build a server: shared config here, finalized by picking a transport.

What's given here -- the server's name, and the approval/guardrail policy its tools carry -- is common to every transport; http/stdio take the params specific to that transport, a URL vs. a command to spawn. Every parameter is spelled out on all three, rather than collected as **kwargs and forwarded, so that a misspelled or unsupported option is a TypeError naming it at the call site -- the way a mistyped Agent attribute is a UserError naming it at construction -- instead of a server that quietly ignores it and misbehaves on connect.

The two transport classes are deliberately absent from __all__: MCPServer is the whole public surface, and a third transport is written by subclassing _MCPServerBase, not by reaching for MCPServerStdio directly.

Hold config shared by every transport, applied when http/stdio is called.

needs_approval (a bool, or an @approval predicate over the remote tool's arguments) and guardrails (@guardrail predicates, bound with .input/.output against a call's arguments and its result) apply to every tool this server exposes -- @tool's two parameters, asked of the server because that's where a remote tool's trust is decided.

Methods:

http(url: str) -> MCPServerStreamableHttp

stdio(
    command: str,
    args: list[str] | None = None,
    *,
    env: dict[str, str] | None = None,
    cwd: str | None = None,
) -> MCPServerStdio

Bases: GuardrailAudit

The outcome of a single Agent.run()/run_sync() call.

output is the agent's final output (parsed into Agent.output_type when it declares one), None unless status is "completed". trace is the hierarchical Trace (agent/LLM/tool/ handoff/guardrail spans) captured for this call, see runa.tracing; always present, whatever the status, because the trace is opened before anything a run can fail on. usage is this call's token usage, same value as Agent.last_usage after the call.

status is "paused" when a tool call needs human approval: resolve each of interruptions on to_state(), then pass that state back to run/run_sync in place of a message. It is "error" when a RunaError (a guardrail tripwire, MaxTurnsExceeded, a model error, ...) stopped the run; error then holds that exception's message.

guardrail_results is the guardrail audit trail: every guardrail that ran (tripped or not, a delegate's included), keyed by the Phase it ran in, whatever the status. The four *_guardrail_results lists GuardrailAudit reads off it are the documented way in. The same trail is on a paused RunState.

to_payload() is how a transport renders all of this as JSON -- one wire shape, owned here rather than re-derived per transport.

Methods:

to_state() -> RunState

to_payload() -> dict[str, Any]

What Agent.run_streamed() returns: iterate it for StreamEvents.

Once iteration ends, run holds the same Run that run() would have returned, paused, completed, or errored.

Wrap events; run is set by the agent once they are exhausted.

Methods:

__aiter__() -> AsyncIterator[StreamEvent]

Per-call model parameters; a Model implementation uses whichever of these its API takes.

"Whichever" is a closed set, not a courtesy: every field here reaches both backends' request body, or is named in tests/test_models.py's closure test as one that deliberately doesn't. A setting that configures nothing is the failure check_model_name exists to prevent, one field over -- the bill and the caller's mental model disagree, with no signal anywhere.

Attributes:

max_retries: int | None = None

Token usage for one or more model calls.

Agent.run/run_sync accumulate every call's Usage into Agent.usage via .add(), and record the latest one on Agent.last_usage.

Methods:

add(other: Usage) -> None

Bases: GuardrailAudit

Enough of a paused run to resume it once its interruptions are approved or rejected.

transcript is the conversation as it stood at the pause (see Transcript): its items end with the assistant message that requested the paused calls. ready_results holds results already computed this turn for calls in that same message that didn't need approval: they're carried forward rather than re-executed on resume.

run_context is the paused run's RunContext, its context and usage so far. How the run governs itself -- the approval ledger, the paused delegates -- is _governance, which a caller reaches only through approve/reject, never directly (see runa._governance).

to_json()/to_string()/from_json()/from_string() let a paused run survive a process restart -- see their docstrings for what is (and isn't) preserved.

Methods:

Attributes:

paused_message: ConversationItem

approve(
    interruption: Interruption, *, always: bool = False
) -> None

reject(
    interruption: Interruption,
    *,
    always: bool = False,
    rejection_message: str | None = None,
) -> None

to_json() -> dict[str, Any]

to_string() -> str

from_json(
    initial_agent: AgentLike, state_json: dict[str, Any]
) -> RunState

from_string(
    initial_agent: AgentLike, state_string: str
) -> RunState

One tool call paused on needs_approval, surfaced to the caller to resolve.

name is the tool's own name, which is all a decision needs: the sticky ledger is keyed by it, and the resumed run looks the tool itself up again off the agent's shape. Carrying the FunctionTool here as well would mean from_json had to rebuild one from a name, which for an MCP tool means connecting to the server just to read a deserialized blob.

Which run a paused call belongs to isn't here either: a call surfaced by a .delegate subagent appears in its caller's interruptions as the very same Interruption, so it is the stash of paused delegates that knows whose it is (runa.paused_delegates), not the interruption and not whichever RunState happens to be holding it.

Bases: Exception

Base class for every exception a Runa agent run can end with.

One message, carried as both the exception's args and its .message, and nothing else: what a failed run accumulated is reported on the Run the turn loop returns in its place (run_internal/run_loop._errored), not hung off the exception on its way up. Every subclass is that plus its docstring: the ones built from structured fields (GuardrailTripwireTriggered, DuplicateToolCallError) keep their own __init__ to compose the message, then hand it here like any other.

Store message as both the exception's args and its .message.

Bases: RunaError

Raised when a run reaches max_turns without producing a final output.

Bases: RunaError

Raised when a run's accumulated token usage passes Agent.max_tokens.

The spend ceiling to MaxTurnsExceeded's call ceiling: max_turns bounds how many times a run may call the model, this bounds how much those calls may cost. Checked after each model call, so the run stops at the first call that crosses the line rather than before it.

Bases: RunaError

Raised when a run passes Agent.timeout seconds without finishing.

The wall-clock ceiling max_turns/max_tokens can't give: a single tool call or model response that hangs would otherwise stall a run indefinitely. Like every RunaError this comes back as Run(status="error") rather than propagating, and the partial trace is still exported, so a timed-out run is as inspectable as a failed one.

Bases: RunaError

Raised when the model does something a Model implementation can't make sense of.

For example: calling a tool that isn't in the request, or returning malformed tool-call JSON.

Bases: RunaError

Raised when the caller has misused the framework itself (bad config, missing credentials).

Bases: RunaError

Raised in place of an exception a run ended with that is none of Runa's own kinds.

A Session that can't read its database, a Hooks method with a bug in it, a Compactor that divides by zero: the extension points a run calls are application code, and the run boundary owes them the same contract it gives a tripped guardrail (Run(status="error"), with the trace around the failure) rather than one that holds only for failures Runa itself declared. The message names the original's type as well as its text, since neither alone identifies it, and the original is logged with its traceback where it was caught, so nothing about it is lost by coming back as a result.

Not raised for OperatorError (a sibling root, deliberately let through) nor for anything deriving from BaseException alone -- asyncio.CancelledError above all, which a caller asking a run to stop must get back as itself.

Name exc's type and message, since neither alone identifies what went wrong.

Bases: BaseModel

One turn for an agent to run: a new message, or a paused run and the decisions resolving it.

Exactly one of message/state -- the two are the same argument of Agent.run, which takes a message or the RunState of a paused run, so a body carrying both (or neither) is a 422 rather than a guess about which one was meant.

Bases: BaseModel

What a human decided about one Interruption of a paused run.

call_id is the one the paused payload reported, and the only handle a client needs: the tool, its arguments and the agent it belongs to are the server's to look back up off the state. always and rejection_message are RunState.approve/.reject's own keywords, named the same here on purpose -- the wire shape of an approval is the Python one.

Lifecycle callbacks for a run; every method is a no-op unless overridden.

Scope is where an instance is put, not which class it is:

• Agent.run(hooks=...) fires for every agent in that one run, the ones reached by handoff/delegate included. Use it for cross-cutting concerns -- metrics, a single audit log for the whole run.
• An Agent subclass's hooks attribute fires only for that agent, in every run it takes part in. Use it for a concern that belongs to one agent's identity.

Both scopes fire for the same event, run-scoped first, and read the same arguments. on_handoff is the one event an agent-scoped instance doesn't see for every turn of its own agent: it notifies the target, the agent the run was handed to, and never the sender.

LoggingHooks (below) is what a run with no hooks= gets.

Methods:

on_agent_start(
    context: RunContext[TContext], agent: AgentLike
) -> None

on_agent_end(
    context: RunContext[TContext],
    agent: AgentLike,
    output: Any,
) -> None

on_handoff(
    context: RunContext[TContext],
    from_agent: AgentLike,
    to_agent: AgentLike,
) -> None

on_tool_start(
    context: RunContext[TContext],
    agent: AgentLike,
    tool: FunctionTool,
) -> None

on_tool_end(
    context: RunContext[TContext],
    agent: AgentLike,
    tool: FunctionTool,
    result: object,
) -> None

on_llm_start(
    context: RunContext[TContext],
    agent: AgentLike,
    system_prompt: str | None,
    input_items: list[ConversationItem],
) -> None

on_llm_end(
    context: RunContext[TContext],
    agent: AgentLike,
    response: Any,
) -> None

Bases: Hooks[Any]

Logs each lifecycle event through the standard logging module, under the runa logger.

Agent.run/run_sync use an instance of this as the default hooks, so every run is logged without the caller having to ask; passing an explicit hooks overrides it. Assigned to an Agent subclass's hooks instead, it logs that one agent's events.

Methods:

on_agent_start(
    context: RunContext[Any], agent: AgentLike
) -> None

on_agent_end(
    context: RunContext[Any], agent: AgentLike, output: Any
) -> None

on_handoff(
    context: RunContext[Any],
    from_agent: AgentLike,
    to_agent: AgentLike,
) -> None

on_tool_start(
    context: RunContext[Any],
    agent: AgentLike,
    tool: FunctionTool,
) -> None

on_tool_end(
    context: RunContext[Any],
    agent: AgentLike,
    tool: FunctionTool,
    result: object,
) -> None

on_llm_start(
    context: RunContext[Any],
    agent: AgentLike,
    system_prompt: str | None,
    input_items: list[ConversationItem],
) -> None

on_llm_end(
    context: RunContext[Any],
    agent: AgentLike,
    response: Any,
) -> None

A handoff switched the agent running this turn.

A raw, provider-shaped fragment of a streamed response, passed through as-is.

One completed item produced mid-stream: a message, a tool call, a tool's output, ...

One eval case: an input, plus optional evidence of what a good run looks like.

expected enables answer-correctness grading; expected_tool enables the deterministic "was it called" (tool-correctness) check; context (retrieval passages the agent should be grounded in) enables faithfulness grading. Any combination is valid, including none of them, in which case only task completion and answer relevance run.

One Case's Run plus every EvaluationResult graded against it.

Attributes:

id: str

passed: bool

failure_reason: str | None

An ordered, iterable collection of Case.

Wrap cases in a list, preserving order.

Methods:

__iter__() -> Iterator[Case]

__len__() -> int

__getitem__(index: int) -> Case

from_jsonl(path: str | Path) -> Dataset

One metric's verdict on one case: deterministic or semantic, same shape either way.

Attributes:

passed: bool

The aggregated result of agent.evaluate(dataset), under the agent's declared name.

Methods:

Attributes:

baseline: dict[str, bool] | None = None

passed: list[CaseReport]

failed: list[CaseReport]

failures: list[CaseReport]

regressions: list[CaseReport]

pass_rate: float

metrics: dict[str, float]

score: float

__str__() -> str

Bases: StrEnum

A metric's outcome for one case.

SKIPPED means the metric didn't apply (e.g. faithfulness with no retrieval context); ERROR means the check itself failed to run (e.g. the judge model call raised). Neither is a score of 0 or 1: a PASS/ FAIL verdict claims to have actually measured something.

Configure what tracing captures: this call for the process, .scoped(...) for one task.

observe(capture_inputs=False) applies the setting to the process-wide default and leaves it there: it is what an application configures itself with, once, at startup. with observe.scoped(capture_inputs=False): applies it to the current task only, and restores whatever that task saw before on exit.

The two scopes are two call sites rather than one name that infers which was meant from whether a with follows it, the way Guardrail.input/.output and Agent.handoff/ .delegate name the choice they make. The inference needed a constructor that wrote the process-wide default for __enter__ to then undo, which made the object single-use (it captured the default it would restore) and the write itself invisible to anyone reading the call site. Naming the scope instead means nothing is captured and nothing is undone.

The scopes differ in reach, deliberately. A block that changed the policy process-wide would mean one of runa.serve's concurrent requests deciding what every other in-flight request captures, so .scoped is a ContextVar. That costs the opposite: a task does not see an override installed by a task that started after it, so the plain call -- not a block held open around the whole application -- is what configures a whole deployment.

Apply the given overrides to the process-wide tracing policy, permanently.

There is nothing to hold on to afterwards: the call is the configuration. An instance is not a context manager, so a with observe(...) written out of habit is a TypeError at that line -- pointing at observe.scoped(...) -- rather than a block whose policy silently outlives it.

Methods:

scoped(
    *,
    capture_inputs: bool | None = None,
    capture_outputs: bool | None = None,
    redact: list[str] | None = None,
    redactor: Callable[[Any], Any] | None = None,
    max_input_bytes: int | None = None,
    max_output_bytes: int | None = None,
    max_tool_result_bytes: int | None = None,
    exporter: TraceExporter
    | list[TraceExporter]
    | None = None,
) -> _ScopedPolicy

One traceable operation: an agent turn, an LLM call, a tool call, a handoff, ...

input/output/error stay None when that data isn't available or was withheld by the active privacy policy (see tracing.config.observe); missing data is never fabricated.

Attributes:

duration: float | None

One span as a person reads it: the tree's shape and its labels, no characters chosen yet.

What Trace.walk yields. It carries everything a renderer needs to draw a row and nothing about how to draw it, so runa traces show can turn these into box-drawing lines and runa ui into nested <div>s without either re-deriving which spans are whose children, what a span type is called, or what a handoff is named once the model's prefix comes off.

span is the raw Span for anything a renderer wants that isn't person-readable yet: its input/output/attributes/status/error.

Attributes:

hands_off: bool

One logical agent execution: a start/end time, metadata, and its Span tree.

spans is a flat list: each Span.parent_id (or None, for a root span) is what gives it shape; __str__ walks that structure to render the tree shown in the "Human-readable trace representation" section of the design.

Methods:

Attributes:

duration: float | None

status: SpanStatus

errors: list[Span]