Documentation

ai.Agent

The default runner. A spec-mode LLM function's direct call runs `Agent.new(client = client).run(Fn@spec(...)).value`; construct it yourself to set the other fields (`$` call-site parameters are a future phase).

Reference version

Signature

class ai.Agent

The default runner. A spec-mode LLM function's direct call runs Agent.new(client = client).run(Fn@spec(...)).value; construct it yourself to set the other fields ($ call-site parameters are a future phase).

The class itself is not generic: none of its configuration involves the output type. Out lives on run, where it is inferred from the spec argument, so no call site needs to name it.

on_event gets every event of the run's journal, in journal order, one time each. A run that ends with an error has delivered everything it recorded before the error leaves run: the reply that did not parse (and every repair attempt before it), the turn the model cut short, the refusal, the tool failure. No event stands for the failure itself: a good run ends with FinalProduced, a failed one with the error.

Source:<builtin>/ai/runner.bamlbytes 2094–21650

Fields

max_steps

int

schema_attempts

int

Static methods

function

new

<__effect_param_0>(
max_steps: int = …,
schema_attempts: int = …,
client: ai.Client | null = …,
tool_errors: ai.tools.ErrorMode = …,
on_event: ((ai.events.Event) -> void throws __effect_param_0) | null = …
) -> ai.Agent throws baml.errors.InvalidArgument

Instance methods

function

_attempt_turn

<Out>(
self,
spec: ai.FunctionSpec<Out>,
attempts_left: int
) -> ai._AcceptedTurn throws baml.errors.Timeout | baml.errors.UnknownError | reflect.errors.CompilationError | ai.errors.Failure

(internal) One accepted model turn, with the within-turn repair loop: when a Complete turn's candidate does not parse, commit the failed turn and a correction request as ordinary events and invoke again, under a fixed attempt budget. Everything that happened is on the record; a repair attempt does not consume a step. Token usage of every attempt is added to total.

function

_deliver

(self, j: ai.Journal, delivered: ai._Delivered) -> void throws never

(internal) Give on_event the events appended since the last delivery, in journal order.

function

_fits_without_text

<Out>(self, turn: ai.ModelTurn) -> bool | null throws baml.errors.UnknownError

(internal) Whether the turn answers with an Out without parsing its text: the provider-decoded output decides, or the turn's media does. null when only parsing the terminal text can tell.

function

_has_media_output

<Out>(self, turn: ai.ModelTurn) -> bool throws baml.errors.UnknownError

(internal) Does this turn carry content a media-shaped Out can be built from? Mirrors the Ok(None) condition of sys_llm's parse_llm_output_for_target: nothing to build from means fall back to the ordinary text parse. Always false when Out holds no media.

function

_media_value

<Out>(
self,
provider: string
) -> Out throws baml.errors.UnknownError | ai.errors.ParseFailed

(internal) Build a media-shaped Out from the turn's content blocks. Only called when _has_media_output holds; the shape-specific errors below are the ported sys_llm messages, thrown after the turn is already on the record.

function

_parse_text

<Out>(self, candidate: string) -> ai.ParsedOutput | null throws never

(internal) The terminal text parsed into an Out, or null when it does not parse.

function

_run_steps

<Out>(
self,
selected: ai.Client,
spec: ai.FunctionSpec<Out>,
delivered: ai._Delivered,
schema_attempts: int
) -> ai.RunResult<Out> throws baml.errors.Timeout | baml.errors.UnknownError | reflect.errors.CompilationError | ai.errors.Failure

(internal) The loop of run: turns, tool calls and the final value. It delivers events as it goes; an error it throws can leave events on the record that it did not deliver, and run delivers those.

function

_validated_schema_attempts

(self) -> int throws baml.errors.InvalidArgument

Implementations

ai.Runner for ai.Agent

Error = baml.errors.InvalidArgument | baml.errors.Timeout | baml.errors.UnknownError | reflect.errors.CompilationError | ai.errors.Failure

Instance methods

Source:<builtin>/ai/runner.bamlbytes 20191–21648