Runs a tool-use conversation until the model stops asking for tools.
Jibu executes every tool in body.tools that carries a :run function.
Jibu removes :run before sending. Every other field passes through.
Tools without :run, such as server tools, go out unchanged.
weather = %{
name: "weather",
description: "Current weather for a city",
input_schema: %{type: "object", properties: %{city: %{type: "string"}}, required: ["city"]},
run: fn %{"city" => city} -> {:ok, "sunny in " <> city} end
}
{:ok, response, messages} =
Jibu.Tools.run(client, %{
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [weather],
messages: [%{role: "user", content: "Weather in Berlin?"}]
}):run receives the tool input as a map with string keys.
It returns {:ok, content} or {:error, content}.
content is a string or a list of content blocks.
An error tuple, a raised exception or an unknown tool name becomes a tool_result with
is_error: true. The model sees the error and can react.
All results of one turn go back in a single user message.
A pause_turn response goes back unchanged, so the model can continue.
The returned messages hold the whole conversation, ending with the final assistant turn.
See the Tools guide for more.
Summary
Functions
Runs the loop.
Functions
@spec run(Req.Request.t(), map() | String.t() | [map()], keyword()) :: {:ok, Jibu.Response.t(), [map()]} | {:error, Jibu.Error.t()}
Runs the loop.
The second argument is a request body or a prompt. A prompt takes the shortcuts of
Jibu.ask/3 except :on_text. Use :on_event to stream.
tools: goes into the body like any other keyword.
Returns {:ok, response, messages} for the first response whose stop_reason is neither
"tool_use" nor "pause_turn". Check that stop_reason for "refusal" or "max_tokens"
before using the answer.
Options
:max_iterations- maximum number of requests, default10.:max_concurrency- maximum number of tools of one turn that run at once, default1.:tool_timeout- milliseconds a tool may run, default:infinity. A tool that exceeds it is killed and returns an error result.:on_event- a function that receives every stream event of every turn. Each turn then goes throughJibu.stream/3.
With :max_concurrency above 1 or a finite :tool_timeout, each tool runs in its own task.