---
title: The Agent Loop and Tool Use
url: https://doc.liz6.com/en/ai/02-Agent/01-the-agent-loop-and-tool-use
locale: en
area: ai
tags:
- agent
- tool-use
- function-calling
- agentic-ai
- claude-code
- managed-agents
- world-model
- qwen-agentworld
- ai
- Agent
date: 2026-06-30
modified: 2026-07-16
description: 'The essential difference between an agent and a chatbot is not that the model is smarter, but that there is an additional loop: model decision → host execution → observe results → re-decision. The model itself executes nothing—security boundaries, permissions, and audits all fall on the host side.'
---
# The Agent Loop and Tool Use
> The essential difference between an agent and a chatbot is not that the model is smarter, but that there is an additional loop: model decision → host execution → observe results → re-decision. The model itself executes nothing—security boundaries, permissions, and audits all fall on the host side.
## Overview
The essential difference between an agent and a chatbot is not that the model is smarter, but that **there is an additional loop**. A chatbot is "input → one output"; an agent is "input → decision → call tool → observe result → re-decision → … → completion". The model itself hasn't changed; what has changed is that the harness wraps it in a **loop that repeatedly feeds back observations**. Seeing this clearly allows you to understand that underneath Claude Code, Cursor, and various "AI agents" lies the same skeleton.
This isn't a new phenomenon. In 2023, function calling / tool use emerged, enabling models to produce **structured tool calls** rather than just text; work like ReAct intertwined "reasoning + action"; by 2024–2026, Anthropic productized this loop incrementally—Claude Code is its command-line incarnation, while Managed Agents move the entire loop to server-side hosting. Understanding the loop is more valuable than memorizing any specific framework.
A counterintuitive but crucial fact: **the model never executes anything itself**. It doesn't actually read files, run commands, or call APIs. It only "speaks": I want to call `read_file` with parameters `{path: ...}`. The **host program** is what actually executes. The model is the brain; the host is the hands and feet. Security boundaries, permissions, and audits all fall on the host side—this fact dictates all subsequent engineering trade-offs.
## Core: The think → act → observe Loop
```mermaid
flowchart TD
M["Model Decision (think) Produces structured tool_use"]
H["Host Executes Tool (act)"]
O["Feed Results Back to Model (observe) tool_result"]
E["Final Answer"]
M -->|tool_use| H
H -->|tool_result| O
O --> M
M -->|"stop_reason = end_turn (no more tool calls)"| E
```
What happens in one API interaction:
1. The host provides the model with a set of **tool definitions** (schema) + the current conversation.
2. The model returns a response. If it wants to use a tool, the response includes a `tool_use` block with `stop_reason: "tool_use"`.
3. The host **executes** the tool, packages the output as `tool_result` (including the corresponding `tool_use_id`), and feeds it back into the messages.
4. Request the model again. Repeat until `stop_reason: "end_turn"` (the model no longer requests tools).
The stopping condition is given by `stop_reason`, which the host must handle via branching:
| stop_reason | Meaning | What the Host Should Do |
|---|---|---|
| `end_turn` | Natural completion | Exit the loop |
| `tool_use` | Wants to call a tool | Execute the tool, feed back tool_result, continue |
| `max_tokens` | Hit output limit | Increase max_tokens or switch to streaming |
| `pause_turn` | Server-side tool loop paused | Pass through as-is; the server resumes automatically |
| `refusal` | Safety refusal | Do not retry verbatim; read stop_details |
## Tools Are the Agent's API to the World
A tool definition = name + description + JSON schema:
```json
{
"name": "get_weather",
"description": "Get current weather for a location. Call when the user asks about current weather.",
"input_schema": {
"type": "object",
"properties": { "location": {"type": "string", "description": "City, e.g. Beijing"} },
"required": ["location"]
}
}
```
The tool's **name, description, and schema are much more important than you might think**—they are the agent's entire interface to understanding the world. The model relies on the description to decide **when** to call, so the description must clearly state "under what circumstances to use it," not just "what it does." Recent Opus models are more "restrained" regarding tools; explicitly stating trigger conditions in the description significantly improves the hit rate for appropriate calls.
`get_weather` is just a minimal example; real-world agent tools cover various domains, but they all share the same skeleton (name + trigger condition description + typed schema):
| Domain | Tool | Key Schema Parameters |
|------|------|------|
| Files | `read_file` / `write_file` / `edit` | `path`, `content`, `old_str`/`new_str` |
| Retrieval | `search_docs` | `query`, `top_k`, `filter` |
| Data | `query_db` | `sql` (read-only) or structured `table`/`where` |
| External API | `send_email` / `create_pr` | `to`/`subject`/`body`, `repo`/`branch` |
| System | `bash` | `command` (opaque, requires careful scrutiny, see below) |
Claude Code itself is this set of tools: `read`/`write`/`edit`/`bash`/`grep`/`glob`; the context7 and code-review-graph (MCP) connected in this session also appear to the model in the same form. **Domains may differ vastly, but what the model sees are "hooks with typed parameters"—this is precisely the value of elevating actions into dedicated tools.**
A few principles you'll hit if you try them:
- **Feed errors back as observations, don't let them crash as exceptions.** When a tool fails, return `tool_result` with `is_error: true` plus a human-readable error message ("City xyz does not exist, please provide a valid city name"). The model will understand and adjust its path, rather than crashing the entire loop.
- **Parallel tool calls:** A single assistant message may contain multiple `tool_use` blocks. After executing them concurrently, **all** `tool_result`s must be placed in a **single** user message when fed back—splitting them into multiple messages subtly trains the model to stop parallelizing.
- **Less is more:** Too many tools cause the model to choose incorrectly; if the toolset is large, use tool search to load on demand rather than dumping everything at once (this also protects prompt caching, see [Context Engineering](/ai/01-models-and-context/01-context-engineering.md)).
## Controlling the Loop: Don't Let It Run Wild
A bare loop is prone to issues. In production, add these brakes:
- **Iteration limit:** `max_iterations` to prevent infinite loops.
- **Budget:** Task budget / monitor cumulative tokens; gracefully wrap up when the limit is reached.
- **Human-in-the-loop:** For dangerous/irreversible actions (sending emails, deleting data, `git push`), require human confirmation—insert approval via a manual loop before each tool execution, or set an "always ask" permission policy for that tool.
- **Permissions/Sandbox:** Commands for tools like `bash` are **untrusted model outputs**; run them in an isolated environment, use an executable whitelist, set timeouts, and log everything. Blacklists are not enough.
Why "elevate" actions into dedicated tools instead of going through `bash` entirely? Because `bash` gives the host only an opaque command string, whereas dedicated tools (like `send_email`) provide hooks with typed parameters, allowing the host to intercept, confirm, render, audit, and schedule in parallel. Rule of thumb: **start with bash for breadth; elevate to dedicated tools when you need scrutiny, rendering, auditing, or parallelism.**
## Workflow or Agent? Don't Rush into Agents
Not all tasks require an agent. For fixed, fully pre-describable processes, use a **deterministic pipeline (workflow)**—code controls every step, calling the model only once when needed—this is more stable, cheaper, and more controllable than an agent.
Before adopting an agent, pass through four gates (if any answer is "no", step back to a simpler layer):
| Criterion | Ask Yourself |
|---|---|
| Complexity | Is the task multi-step and impossible to fully specify in advance? ("Turn design docs into a PR" is; "Extract titles from a PDF" is not) |
| Value | Is the result worth the higher cost and latency? |
| Viability | Is the model actually good at this type of task? |
| Cost of Error | Can errors be detected and rolled back? (Tests/reviews/rollback mechanisms exist) |
## Best Practices
- **Remember: the model never executes; the host does.** Security boundaries, permissions, and audits are all on the host side—this dictates all subsequent engineering trade-offs (see [Security & Protection](/ai/03-applications-and-production/04-security-and-protection.md)).
- **Write tool descriptions clearly stating "when to use," not just "what it does."** The model relies on descriptions to decide when to call; specifying trigger conditions significantly improves the hit rate for appropriate calls.
- **Feed errors back as observations, don't let them crash as exceptions.** On failure, return `tool_result` + `is_error: true` + a human-readable message; the model will adjust its path.
- **Feed parallel results back in a single user message.** Splitting them into multiple messages subtly trains the model to stop parallelizing.
- **Keep it lean; use tool search to load on demand if there are many tools.** This prevents incorrect selection and preserves [prompt caching](/ai/01-models-and-context/01-context-engineering.md).
- **Add brakes to bare loops.** Iteration limits, token budgets, human-in-the-loop for dangerous actions, and bash sandbox whitelists.
- **Start with bash for breadth; elevate to dedicated tools when scrutiny, rendering, auditing, or parallelism is needed.**
- **Don't use an agent if a workflow can handle it.** Only proceed after passing the complexity/value/viability/error cost gates.
## Trade-offs and Failure Modes
- **Infinite loops:** The model repeatedly calls the same tool without converging → Set an iteration limit + provide clearer next steps in the tool_result.
- **Hallucinated tool calls:** Calling a non-existent tool or fabricating parameters → Use strict schemas (`strict: true`), clear descriptions, and tool_choice constraints.
- **Observations blowing up context:** A tool output of tens of thousands of lines fills the window → Truncate/summarize tool outputs on the host side, or use context editing to clean up old results (see [Context Engineering](/ai/01-models-and-context/01-context-engineering.md)).
## This Is the Loop You Use Daily
[Claude Code](/) itself is this loop: it turns `read`/`write`/`edit`/`bash`/`grep`/`glob` into tools, the model decides, it executes, and results are fed back. OMC (oh-my-claudecode) performs **multi-agent orchestration** on top of this loop—splitting exploration, planning, execution, and review across different agents. Once you understand the loop, these upper-layer frameworks are just "loop + scheduling strategy."
Another form is **Managed Agents**: Anthropic **hosts the entire loop** and provides a container for each session as a workspace (bash/files/code run in the container, the loop runs in Anthropic's orchestration layer). Its iron rule is:
Do not call `agents.create()` on every run (this creates orphaned agents); agents are versioned persistent objects, created once and referenced repeatedly.
## Frontier: Training a "Simulator" for Agent Training — Qwen-AgentWorld
The agents discussed above run loops in a **real environment**—actually calling APIs, actually executing commands. A frontier research direction asks the opposite: Can we train a model to **play the role of that environment**? Let the agent model interact with it as if interacting with the real environment?
Alibaba's [Qwen-AgentWorld-35B-A3B](https://huggingface.co/Qwen/Qwen-AgentWorld-35B-A3B) does exactly this. Note: **It is not an agent.** It does not call tools, execute commands, or produce final answers. It is a **world model**—playing the role of the environment, receiving the agent's actions, and predicting what observation the environment should return. Role analogy: In reinforcement learning, it is the gym's simulator, not the policy trained inside the simulator.
### Architecture and Training
Based on Qwen3.5-35B-A3B-Base, MoE architecture: 35B total parameters, 256 experts, 8 routed + 1 shared activated per token (~3B activated parameters). 40 layers, using hybrid attention: 10 repeated blocks, each block = 3×(Gated DeltaNet→MoE)→1×(Gated Attention→MoE). Gated DeltaNet is a variant of linear attention that reduces the O(n²) complexity of long-sequence attention to near-linear, supporting 256K context.
Three-stage training makes it a **native world model** (aimed at environment modeling from the pre-training stage, not an afterthought added to a general LLM): CPT (injecting environment knowledge) → SFT (activating next-state prediction reasoning) → RL/GSPO (improving simulation fidelity).
### Simulating Seven Types of Environments
Covers MCP (tool calling), Search, Terminal, Software Engineering (SWE), Android, Web, OS—text and GUI interaction environments unified in one model. The agent initiates actions toward it, and it outputs observations as responses after reasoning about state transitions in a `` block. This corresponds exactly to the "observe" step in the agent loop.
### Why It's Valuable
Agent training and evaluation are bottlenecked by the "environment"—real environments are slow, expensive, have side effects, and are non-reproducible. A world model can **controllably simulate** these environments using language: **not only reproducing real scenarios but also constructing scenarios that don't exist in the real environment** (controllable perturbations, fictional worlds), allowing the agent to trial-and-error, run RL, and evaluate under conditions where real environment experiments are impossible. It also demonstrates zero-shot generalization: it can provide meaningful simulations for environments not seen during training (e.g., OpenClaw).
### Why 3B Activations Work for a World Model but Not for an Agent
AgentWorld performs **single-step next-state prediction**: receiving an action, predicting what observation the environment returns. This is single-step reasoning—it doesn't need to maintain a serial chain of "what I did in step one, what I should do in step two" in its mind. In contrast, an agent's tool calling is **multi-step serial reasoning**—each step's decision depends on the previous step's result and the initial intent. Single-step reasoning with 3B activated parameters is sufficient for next-state prediction, but cannot support the multi-step agent loop that requires maintaining intent consistency. See the discussion on activated parameters and reasoning depth in [Model Architecture](/ai/01-models-and-context/03-model-architecture-dense-vs-moe.md).
### How to Measure if a World Model is Good
AgentWorldBench quantifies scores by environment domain across five dimensions (Format / Factuality / Consistency / Realism / Quality) into a 0–100 scale, with an overall mean of 56.39. Reference: GPT-5.4 scores 58.25, Claude Opus 4.8 scores 56.59—a language world model with only 3B activated parameters achieves simulation fidelity nearly on par with the strongest general models, far exceeding the same-size base Qwen3.5-35B-A3B (47.73). This also means this world model path doesn't require datacenter-level compute: consumer-grade hardware can run a decent agent simulation environment.
## References
- **Anthropic Official Docs**: Tool Use Overview, Building Effective Agents, Managed Agents (platform.claude.com)
- **Research**: "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., 2022)
- **Frontier Model**: [Qwen-AgentWorld-35B-A3B](https://huggingface.co/Qwen/Qwen-AgentWorld-35B-A3B)
*Keywords: agent loop, think-act-observe, tool use, function calling, tool schema, tool_result, stop_reason, end_turn, parallel tool use, is_error, human-in-the-loop, workflow vs agent, Managed Agents, agent toolset, world model, Qwen-AgentWorld, AgentWorldBench, MoE*