Mutable state for an agent run.
Tracks the conversation history, turn count, token usage, and current status. Passed through each iteration of the agent loop.
deadline is the monotonic time in milliseconds (see
System.monotonic_time/1) by which the run's provider requests must
finish; Alloy.Agent.Turn.run_loop/2 sets it. Middleware that makes its
own provider request, as compaction does, should finish by it.
Summary
Functions
Append messages to the conversation history.
Append tool execution metadata for the current run.
Increment the turn counter.
Initialize state from config and optional existing messages.
Extract the text from the last assistant message.
Extract the thinking/reasoning text from the most recent assistant message
that carries any. Returns nil when no assistant message has thinking.
Merge provider-owned state returned by the model backend.
Merge agent-loop runtime metadata for the current run.
Merge usage from a provider response.
Return the conversation history in chronological order, the same as
state.messages.
Prepares request inputs from :before_completion middleware.
Replace the latest provider response metadata for this run.
Types
@type status() :: :idle | :running | :completed | :error | :max_turns | :halted
@type t() :: %Alloy.Agent.State{ agent_id: String.t(), config: Alloy.Agent.Config.t(), deadline: integer() | nil, error: term() | nil, messages: [Alloy.Message.t()], provider_response_metadata: map(), provider_state: map(), run_metadata: map(), started_at: integer() | nil, status: status(), stop_reason: Alloy.Provider.stop_reason() | nil, tool_calls: [map()], tool_defs: [map()], tool_fns: %{required(String.t()) => Alloy.Tool.Registry.tool()}, tool_schema_cache: map(), turn: non_neg_integer(), usage: Alloy.Usage.t() }
Functions
@spec append_messages(t(), [Alloy.Message.t()] | Alloy.Message.t()) :: t()
Append messages to the conversation history.
state.messages always holds the full history in chronological order,
so middleware can read it directly.
Append tool execution metadata for the current run.
Increment the turn counter.
@spec init(Alloy.Agent.Config.t(), [Alloy.Message.t()]) :: t()
Initialize state from config and optional existing messages.
Extract the text from the last assistant message.
Returns "" when that message has no text blocks and nil when there is
no assistant message.
Extract the thinking/reasoning text from the most recent assistant message
that carries any. Returns nil when no assistant message has thinking.
Merge provider-owned state returned by the model backend.
Merge agent-loop runtime metadata for the current run.
Merge usage from a provider response.
@spec messages(t()) :: [Alloy.Message.t()]
Return the conversation history in chronological order, the same as
state.messages.
Prepares request inputs from :before_completion middleware.
Accepts :messages, :tools, :system_prompt, and :provider (the same
provider tuple accepted by Alloy.run/2). Changes persist for later turns.
Tools and their wire definitions are rebuilt together. Provider changes
re-derive model limits and discard previous opaque provider state; pass an
explicit provider_state in the new provider config to restore it.
Run counters, deadlines, usage, and tool history are preserved.
Replace the latest provider response metadata for this run.