AshAi.ToolLoop (ash_ai v1.5.6)

Copy Markdown View Source

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.

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

pending_tool_calls(messages)

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.

resume(messages, decisions, opts)

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)).

run(messages, opts)

Runs the tool loop synchronously.

Returns {:ok, %Result{}}, including when the loop stops to wait for approvals, or {:error, reason}.

stream(messages, opts)

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{}}