A plain language model can only write text. An AI agent can also take actions: search the web, run code, read files, check a database or control a device, then decide what to do next based on what happened. That's the difference between an assistant that tells you how to do something and one that does it.
Tools: how a model takes action
The model itself never runs anything. Instead, your program describes some tools it's allowed to use, each with a name, a description and the inputs it needs. When the model decides a tool would help, it replies with a request like "call get_temperature with room = garage". Your code runs the tool and sends back the result. The model then carries on with that new information.
The agent loop
An agent repeats this loop until the job is finished. Asked "Is it warm enough in the garage to paint?", it might check the temperature, check the humidity, then answer. A coding agent might read files, edit one, run the tests, see a failure and try again, all without a human in between.
A small example in Python
This uses Anthropic's Python library. The tool here is a pretend sensor, but it could just as easily read a real one.
import anthropic
client = anthropic.Anthropic()
tools = [{
"name": "get_temperature",
"description": "Get the current temperature in °C for a room in the house.",
"input_schema": {
"type": "object",
"properties": {"room": {"type": "string", "description": "e.g. garage, kitchen"}},
"required": ["room"],
},
}]
def get_temperature(room):
readings = {"garage": 9.5, "kitchen": 20.1} # pretend sensors
return str(readings.get(room, "unknown room"))
messages = [{"role": "user", "content": "Is the garage warm enough to paint? Paint needs 10 °C."}]
while True:
response = client.messages.create(
model="claude-haiku-5-5", max_tokens=4096, tools=tools, messages=messages
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
break # no more tools needed
results = []
for block in response.content:
if block.type == "tool_use":
output = get_temperature(**block.input)
results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
messages.append({"role": "user", "content": results})
print("".join(b.text for b in response.content if b.type == "text"))
The model asks for the garage temperature, gets 9.5, and explains that it's just below the 10 °C the paint needs. New to the API? Start with your first AI API program.
Keeping agents safe and useful
- Give the fewest tools needed. A tool that can only read a sensor is far safer than one that can run any command.
- Ask a human before risky actions, such as sending emails, spending money or deleting files.
- Treat what tools return as information, not instructions. A web page or email could contain text written to trick the agent. This is called prompt injection.
- Set limits on how many steps the loop can take and how much it can spend.
- Write clear tool descriptions. The model decides when to use a tool based on its description, so explain what it does and when to use it.
Going deeper
Designing good tools
- Few, clear tools beat many overlapping ones. If two tools could both do a job, the model may pick the wrong one.
- Write descriptions for a newcomer. Say what the tool does, when to use it, what each input means and what it returns.
- Return useful errors. If a tool fails, send back a clear message, marked as an error, such as "Room 'garge' not found. Valid rooms: garage, kitchen". The model can often correct itself.
- Keep results small. Returning a 10,000-line log fills the context window. Summarise, paginate or let the model search instead.
Parallel tool calls
Models can ask for several tools in one turn, such as checking three rooms at once. Your loop should run every tool_use block in the reply and return all the results together in the next message, each matched to its tool_use_id.
Managing context on long tasks
Every step adds tool calls and results to the conversation, so long-running agents can fill their context window. Common fixes are trimming old tool results, summarising earlier progress, and letting the agent save notes to a file it can read later. See context windows explained.
MCP: a standard way to connect tools
The Model Context Protocol (MCP) is an open standard, introduced by Anthropic in 2024, for connecting AI applications to tools and data. Instead of writing custom integrations for each app, a service provides an MCP server once, and any MCP-compatible app can use it. Many AI apps and developer tools now support it.
Safety in depth
- Run agents that execute code inside a sandbox or container, with no access to secrets they don't need.
- Use separate, limited credentials for the agent, never your personal admin account.
- Log every tool call, so you can see exactly what happened.
- Require human approval for anything irreversible, and test what happens when a tool returns misleading content.
Measuring agents
Judge agents on whole tasks: did they finish, was the result correct, and how many steps and tokens did it take? Run the same tasks several times, because agents can take different paths on each run.
Sources
The main references behind this guide. Numbers we worked out ourselves, such as the code outputs, come from running the code.