Alloy.Agent.State (alloy v0.10.1)

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.

Summary

Types

status()

t()

Functions

append_messages(state, messages)

Append messages to the conversation history.

append_tool_calls(state, tool_calls)

Append tool execution metadata for the current run.

cleanup(state)

Clean up resources owned by this state. No-op currently; reserved for future resource management.

increment_turn(state)

Increment the turn counter.

init(config, messages \\ [])

Initialize state from config and optional existing messages.

last_assistant_text(state)

Extract the text from the last assistant message.

materialize(state)

Flush the accumulator into the messages field.

merge_provider_state(state, provider_state)

Merge provider-owned state returned by the model backend.

merge_run_metadata(state, metadata)

Merge agent-loop runtime metadata for the current run.

merge_usage(state, response_usage)

Merge usage from a provider response.

messages(state)

Return messages in chronological order.

put_provider_response_metadata(state, metadata)

Replace the latest provider response metadata for this run.

Types

status()

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

t()

@type t() :: %Alloy.Agent.State{
  agent_id: String.t(),
  config: Alloy.Agent.Config.t(),
  current_task: {reference(), pid(), binary()} | nil,
  error: term() | nil,
  messages: [Alloy.Message.t()],
  messages_new: [Alloy.Message.t()],
  pending_requests: term(),
  provider_response_metadata: map(),
  provider_state: map(),
  run_metadata: map(),
  started_at: integer() | nil,
  status: status(),
  tool_calls: [map()],
  tool_defs: [map()],
  tool_fns: %{required(String.t()) => module()},
  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.

Uses an internal accumulator for O(1) append. Call messages/1 to retrieve the full list in chronological order.

append_tool_calls(state, tool_calls)

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

Append tool execution metadata for the current run.

cleanup(state)

@spec cleanup(t()) :: :ok

Clean up resources owned by this state. No-op currently; reserved for future resource management.

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.

materialize(state)

@spec materialize(t()) :: t()

Flush the accumulator into the messages field.

After this call, state.messages contains the full chronological list and state.messages_new is empty. Call at process boundaries where code reads state.messages directly.

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 messages in chronological order.

Flushes the internal accumulator and returns the full message list.

put_provider_response_metadata(state, metadata)

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

Replace the latest provider response metadata for this run.