Alloy.Agent.State (alloy v0.13.0)

Copy Markdown View Source

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

status()

@type status() :: :idle | :running | :completed | :error | :max_turns | :halted

t()

@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

append_messages(state, messages)

@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_calls(state, tool_calls)

@spec append_tool_calls(t(), [map()]) :: t()

Append tool execution metadata for the current run.

increment_turn(state)

@spec increment_turn(t()) :: t()

Increment the turn counter.

init(config, messages \\ [])

@spec init(Alloy.Agent.Config.t(), [Alloy.Message.t()]) :: t()

Initialize state from config and optional existing messages.

last_assistant_text(state)

@spec last_assistant_text(t()) :: String.t() | nil

Extract the text from the last assistant message.

Returns "" when that message has no text blocks and nil when there is no assistant message.

last_assistant_thinking(state)

@spec last_assistant_thinking(t()) :: String.t() | nil

Extract the thinking/reasoning text from the most recent assistant message that carries any. Returns nil when no assistant message has thinking.

merge_provider_state(state, provider_state)

@spec merge_provider_state(t(), map() | nil) :: t()

Merge provider-owned state returned by the model backend.

merge_run_metadata(state, metadata)

@spec merge_run_metadata(t(), map() | nil) :: t()

Merge agent-loop runtime metadata for the current run.

merge_usage(state, response_usage)

@spec merge_usage(t(), map()) :: t()

Merge usage from a provider response.

messages(state)

@spec messages(t()) :: [Alloy.Message.t()]

Return the conversation history in chronological order, the same as state.messages.

prepare(state, opts)

@spec prepare(t(), keyword()) :: t()

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.

put_provider_response_metadata(state, metadata)

@spec put_provider_response_metadata(t(), map() | nil) :: t()

Replace the latest provider response metadata for this run.