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 (seeAlloy.Message.text/1):""when that message has no text blocks (it only called tools, or the output was cut off),nilonly when the conversation has no assistant message. With:stop_after_tool, this is the selected tool's final content instead; its metadata is inmetadata.final_tool:thinking— the final assistant thinking/reasoning text (ornilif 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), ornilif no response arrived. Check for:max_tokensto detect a truncated answer on a:completedrun.:turns— number of agent loop iterations:error— error term (ornilon success):request_id— correlation ID for async requests (ornilfor sync)
Summary
Types
@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
@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}.
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).