Alloy.Result (alloy v0.13.0)

Copy Markdown View Source

Structured result from an agent run.

Returned by Alloy.run/2 and Alloy.stream/3. Implements Access for bracket-syntax compatibility (result[:text]).

Fields

  • :text — the text of the last assistant message (see Alloy.Message.text/1): "" when that message has no text blocks (it only called tools, or the output was cut off), nil only when the conversation has no assistant message. With :stop_after_tool, this is the selected tool's final content instead; its metadata is in metadata.final_tool
  • :thinking — the final assistant thinking/reasoning text (or nil if none), so callers need not dig it out of the last message's content blocks
  • :messages — full conversation history
  • :usage — accumulated %Alloy.Usage{} token counts
  • :tool_calls — list of tool execution metadata maps
  • :metadata — auxiliary result metadata such as provider-owned state
  • :status — final run status (:completed, :max_turns, :error, :halted)
  • :stop_reason — why the model stopped on the last provider response (:end_turn, :tool_use, :max_tokens, :refusal, :pause_turn), or nil if no response arrived. Check for :max_tokens to detect a truncated answer on a :completed run.
  • :turns — number of agent loop iterations
  • :error — error term (or nil on success)
  • :request_id — correlation ID for async requests (or nil for sync)

Summary

Functions

Build a Result from a final State.

Tags a result the way Alloy.run/2 returns it.

Types

t()

@type t() :: %Alloy.Result{
  error: term() | nil,
  messages: [Alloy.Message.t()],
  metadata: map(),
  request_id: binary() | nil,
  status: Alloy.Agent.State.status(),
  stop_reason: Alloy.Provider.stop_reason() | nil,
  text: String.t() | nil,
  thinking: String.t() | nil,
  tool_calls: [map()],
  turns: non_neg_integer(),
  usage: Alloy.Usage.t()
}

Functions

from_state(state)

@spec from_state(Alloy.Agent.State.t()) :: t()

Build a Result from a final State.

Extracts text, messages, usage, tool calls, status, turns, and error from the state. The request_id is left as nil — async callers overlay it via %{result | request_id: id}.

wrap(result)

@spec wrap(t()) :: {:ok, t()} | {:error, t()}

Tags a result the way Alloy.run/2 returns it.

{:ok, result} when the run completed or stopped at :max_turns; {:error, result} for every other status (:error, :halted).