Tool Runtime (Tool Loop)

Applies to: 4.0.8.1+

This page covers the full runtime process of tool calling.

1) End-to-end flow

2) Planning stage (PLAN)

Default planner builds a standalone ModelRequest with:

• .input({ user_input, user_extra_requirement, available_tools })
• .info({ done_plans, last_round_result, round_index, max_rounds })
• .instruct([...])
• .output({ next_action, execution_commands[] })

Each execution_commands[] item contains:

• purpose
• tool_name
• tool_kwargs
• todo_suggestion

3) instant short-circuit

Default planner listens on instant:

So next_action=response can end planning early.

4) Execution stage (EXECUTE)

Default executor:

1. reads execution_commands
2. creates semaphore from tool.loop.concurrency
3. calls async_call_tool(tool_name, tool_kwargs)
4. emits normalized records:
   • purpose/tool_name/kwargs/todo_suggestion/success/result/error

5) Convergence and injection

After loop ends:

• with records:
  • to_action_results(records) -> prompt.action_results
  • prompt.extra_instruction for evidence quoting
  • extra.tool_logs appended to final result
• without records:
  • no tool result injection

6) Runtime controls

• tool.loop.enabled
• tool.loop.max_rounds
• tool.loop.concurrency
• tool.loop.timeout

Next: Tool Handlers (Default & Replace)