Manages a ReqLLM conversation loop with tool calls.
This module is the primary orchestration API for tool-enabled conversations.
Each assistant tool-call turn is appended before its tool results. Earlier messages remain unchanged, including their reasoning and provider metadata.
When :system_prompt is given, its result is sent as a system message ahead
of messages on every model request. It is not part of the returned
Result.messages, so pass the same option when continuing a conversation
from those messages.
Approvals
Pass :approve_tool_call, a function that receives each tool call
(%{id: id, name: name, arguments: args}) and the tool context, and returns
:ok, {:deny, reason}, or :ask. Approved calls run and denied calls get
an error result as usual. When any call in a round needs approval, the loop
finishes the other calls of that round and stops, returning a Result with
status: :awaiting_approval and the calls in pending_approvals.
The loop keeps no state between calls. To resume, call run/2 or stream/2
again with the returned messages (which end in the paused tool round) and an
:approvals map from call id to :approve or {:deny, reason}. Calls
without a decision go through :approve_tool_call again. resume/3 is a
shorthand.
If the conversation moves on instead (a user message follows a paused round), each unanswered call is sent to the model with a fixed "not run" result, so the history stays valid and identical across requests.
Persisting turns
stream/2 emits {:message, message} for every message the loop adds to
the conversation: each assistant turn (with its reasoning and provider
metadata) and each tool result. Store them with AshAi.Transcript.to_parts/2
to replay turns exactly, which keeps prompt caching and reasoning intact
across turns and lets a paused turn resume later.
Tool search
Pass tool_search: true (or options) to defer tools until the model
searches for them with the provider's built-in tool search. See
AshAi.ToolSearch.
Images in tool results
A tool can return content parts with images, as AshAi.Mcp.Client tools
do. The model receives them when it accepts image input and its provider's
API carries images in tool results: Anthropic's, Google's, and OpenAI's
Responses API. Otherwise each image is described in text. The conversation
keeps the images either way, so a later request to a model that accepts
them still sends them.
Pass tool_result_images: true to always send them, for a provider that
accepts them but isn't recognized, or false to always describe them, for
example behind a gateway that drops them.
Summary
Functions
The tool calls of a paused round: calls in the last assistant message that have no result, when nothing but tool results follows that message.
Resumes a loop that stopped for approvals.
Runs the tool loop synchronously.
Streams events from the tool loop.
Functions
The tool calls of a paused round: calls in the last assistant message that have no result, when nothing but tool results follows that message.
Resumes a loop that stopped for approvals.
decisions maps tool call ids to :approve or {:deny, reason}. Shorthand
for run(messages, Keyword.put(opts, :approvals, decisions)).
Runs the tool loop synchronously.
Returns {:ok, %Result{}}, including when the loop stops to wait for
approvals, or {:error, reason}.
Streams events from the tool loop.
Content events are emitted as chunks arrive. Complete assistant messages and usage are assembled after each provider response ends. Halting enumeration closes the active provider stream without starting another iteration.
Events:
{:content, text}{:thinking, text}{:tool_call, %{id: id, name: name, arguments: args}}{:tool_result, %{id: id, result: result}}{:message, %ReqLLM.Message{}}- an assistant turn or tool result added to the conversation{:approval_required, [%{id: id, name: name, arguments: args}]}{:paused, [%{call: call, reason: reason}]}{:iteration, %IterationEvent{}}{:error, reason}{:done, %Result{}}