"One loop & Bash is all you need" — One tool + one loop = one Agent.
Harness Layer: The Loop — the first bridge between the model and the real world.
The Problem
You ask the model: "List the files in my directory and run XXX.py."
The model can output a bash command, but once it's done outputting, it stops — it won't execute the command on its own, and it won't keep reasoning based on the result.
You could run it manually, paste the output back into the chat, and let it continue. Next command comes out, you run it again, paste it back.
Every round-trip, you're the middle layer. Automating that is what this chapter is about.
The Solution
A while True loop: keep going when the model calls a tool, stop when it doesn't. The loop checks the response content blocks directly:
| Signal | Meaning | Loop Action |
|---|---|---|
Contains a tool_use block | Model requests a tool call | Execute → feed result back → continue |
Contains no tool_use block | Model did not call a tool | Exit loop |
How It Works
Let's translate this process into code. Step by step:
Step 1: Start with the user's question as the first message.
messages = [{"role": "user", "content": query}]Step 2: Send the messages and tool definitions to the LLM.
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)Step 3: Append the model's response and check whether it called a tool. No tool call → done.
messages.append({"role": "assistant", "content": response.content})
tool_calls = [
block for block in response.content if block.type == "tool_use"
]
if not tool_calls:
returnOnly concrete tool_use blocks enter the execution stage, so the loop never appends an empty tool-result message.
Step 4: Execute the tool the model requested and collect the results.
results = []
for block in tool_calls:
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})Step 5: Append the tool results as a new message and go back to Step 2.
messages.append({"role": "user", "content": results})Assembled into a complete function:
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
messages.append({"role": "assistant", "content": response.content})
tool_calls = [
block for block in response.content if block.type == "tool_use"
]
if not tool_calls:
return
results = []
for block in tool_calls:
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})Just over 30 lines — that's the minimal runnable agent harness kernel. It's not intelligence itself, but the smallest runtime framework that lets the model keep acting. The model decides (whether to call a tool, which one), the harness executes (calls the tool and appends the result as a new message). The next 16 chapters all add mechanisms on top of this loop. The loop itself never changes.
Try It
Safety notice: The code executes shell commands generated by the model. Run it in a temporary test directory to avoid affecting your project files. s03 adds permission controls.
Setup (first run):
pip install -r requirements.txt
cp .env.example .env
# Edit .env, fill in ANTHROPIC_API_KEY and MODEL_IDRun:
python s01_agent_loop/code.pyTry these prompts:
Create a file called hello.py that prints "Hello, World!"List all Python files in this directoryWhat is the current git branch?
What to watch for: When does the model call a tool (loop continues), and when does it not (loop ends)?
#!/usr/bin/env python3
"""
s01_agent_loop.py - The Agent Loop
The entire secret of an AI coding agent in one pattern:
while True:
response = LLM(messages, tools)
if response contains no tool_use:
break
execute tools
append results
+----------+ +-------+ +---------+
| User | ---> | LLM | ---> | Tool |
| prompt | | | | execute |
+----------+ +---+---+ +----+----+
^ |
| tool_result |
+---------------+
(loop continues)
This is the core loop: feed tool results back to the model
until the model decides to stop. Later chapters add policy,
hooks, and lifecycle controls around it.
Usage:
pip install anthropic python-dotenv
ANTHROPIC_API_KEY=... python s01_agent_loop/code.py
"""
import os
import subprocess
try:
import readline
# #143 UTF-8 backspace fix for macOS libedit
readline.parse_and_bind('set bind-tty-special-chars off')
readline.parse_and_bind('set input-meta on')
readline.parse_and_bind('set output-meta on')
readline.parse_and_bind('set convert-meta off')
except ImportError:
pass
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv(override=True)
if os.getenv("ANTHROPIC_BASE_URL"):
os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]
ENVIRONMENT_PROMPT = (
"Windows: the bash tool runs through cmd.exe; use cmd.exe syntax, not Unix "
"Bash or PowerShell syntax"
if os.name == "nt"
else "Unix-like: the bash tool runs the system shell"
)
SYSTEM = (
f"You are a coding agent at {os.getcwd()}. Environment: {ENVIRONMENT_PROMPT}. "
"Use bash to solve tasks. Act, don't explain."
)
# -- Tool definition: just bash --
TOOLS = [{
"name": "bash",
"description": "Run a shell command.",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
"required": ["command"],
},
}]
# -- Tool execution --
def run_bash(command: str) -> str:
dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
if any(d in command for d in dangerous):
return "Error: Dangerous command blocked"
try:
r = subprocess.run(command, shell=True, cwd=os.getcwd(),
capture_output=True, text=True, errors="replace", timeout=120)
out = (r.stdout + r.stderr).strip()
return out[:50000] if out else "(no output)"
except subprocess.TimeoutExpired:
return "Error: Timeout (120s)"
except (FileNotFoundError, OSError) as e:
return f"Error: {e}"
# -- The core pattern: a while loop that calls tools until the model stops --
def agent_loop(messages: list):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
# Append assistant turn
messages.append({"role": "assistant", "content": response.content})
# If the model didn't call a tool, we're done
tool_calls = [
block for block in response.content if block.type == "tool_use"
]
if not tool_calls:
return
# Execute each tool call, collect results
results = []
for block in tool_calls:
print(f"\033[33m$ {block.input['command']}\033[0m")
output = run_bash(block.input["command"])
print(output[:200])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
# Feed tool results back, loop continues
messages.append({"role": "user", "content": results})
# -- Entry point --
if __name__ == "__main__":
print("s01: Agent Loop")
print("Enter a question, press Enter to send. Type q to quit.\n")
history = []
while True:
try:
# \001/\002 tell Readline the ANSI escapes have zero display width.
query = input("\001\033[36m\002s01 >> \001\033[0m\002")
except (EOFError, KeyboardInterrupt):
break
if query.strip().lower() in ("q", "exit", ""):
break
history.append({"role": "user", "content": query})
agent_loop(history)
# Print the model's final text response
response_content = history[-1]["content"]
if isinstance(response_content, list):
for block in response_content:
if getattr(block, "type", None) == "text":
print(block.text)
print()
What's Next
Right now the model only has bash — reading files requires cat, writing files requires echo ... >, finding files requires find. Ugly and error-prone.
Source and license
- Adapted from shareAI-lab/learn-claude-code / s01_agent_loop/README.md (shareAI-lab contributors, License MIT, ce8f9f1)