Your code talks to Claude through Anthropic's API, a web service a program calls. The easy way in is Anthropic's SDK, a library for your language. In Python that's pip install anthropic. One call sends a list of messages and gets Claude's reply back:
from anthropic import Anthropic
client = Anthropic() # reads ANTHROPIC_API_KEY from the environment
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
To carry on a conversation, your code keeps the messages in a list and sends the whole list with every call.
The API key stays on the server
The SDK finds your API key in the ANTHROPIC_API_KEY environment variable. Treat the key like a credit card number: whoever has it runs up charges on your account. So it lives in an environment variable on the server, never in the browser, and never in a file you commit: Anthropic names keys committed to public repos as a frequent cause of leaks. Anthropic's TypeScript SDK is built for server-side code, and it refuses to run in a web browser unless you switch that on, so the key isn't exposed. In the practice project, the call belongs in the FastAPI backend, not in the TypeScript website.
A tool call
You can give Claude tools: functions in your code, each with a name, a description and a JSON Schema for its input. Claude never runs anything itself. When it wants a tool, its reply ends with stop_reason: "tool_use" and holds a tool_use block: the tool's name, an id and the input. Your code runs the function and sends the output back in a tool_result block carrying the same id.
An agent is that call in a loop
An agent is that call repeated in a loop, running the tools Claude asks for and sending the results back, until a reply asks for no more tools; Claude Code runs on the same loop.
Going deeper
6 min read · Going deeper not read
Why it exists
Some of Matt's Skills hand work to sub-agents. ask-matt's phase boundaries, for one, offer a Subagent: "Send the task to its own context window and get a report back." In his AI Engineer workshop (2026-04-24), Matt named the problem underneath: "LLMs are kind of like the guy from Memento, right? They just continually forget." They "keep resetting back to the base state." Matt is talking about sessions, but the same forgetting holds for every single API call: the model keeps nothing between calls, which is why the short part's loop sends the whole history each time. In the same workshop he gave a one-line definition of a sub-agent: it "has essentially gone and called another LLM which has an isolated context window".
This topic opens the box. A sub-agent, an agent and a tool call are all built from the one SDK call in the short part.
How it works underneath
Anthropic's docs call tool use a contract. Your code says which operations exist and what shape their inputs take. Claude decides when to call them. For tools your code runs, every tool call is a round trip: the model asks, you run it, you report back, the model goes on.
Anthropic's own minimal Python loop, from its "Build a tool-using agent" tutorial, is a while loop on :
Each turn, the loop saves Claude's reply and the tool's result into messages, then calls again with the whole history. Any other stop reason ends it: "end_turn" means Claude has a final answer, while "max_tokens" or "refusal" are stops your code should handle. That tutorial's later steps run every tool_use block in a reply, not just the first, and send a failed tool's error back with is_error: true, so Claude can retry or ask.
the model asks
you run it
you report back
the model goes on
Any other stop reason ends it
every tool call is a round trip
Where does the word "agent" come from? Anthropic's "Building effective agents" (Erik S. and Barry Zhang, 2024-12-19) draws the line by who decides the path. What it calls workflows are "systems where LLMs and tools are orchestrated through predefined code paths." Agents are "systems where LLMs dynamically direct their own processes and tool usage". Under the hood, agents "are typically just LLMs using tools based on environmental feedback in a loop." The loop above is that idea in code.
Anthropic's "Autonomous agent" diagram, from "Building effective agents" (2024-12-19). From anthropic.com, 30 October 2026.
The post's advice is to find "the simplest solution possible" and to "start by using LLM APIs directly", because frameworks hide the prompts and responses underneath. A note added to the post since says much of the tooling it lists has changed since December 2024. The definitions haven't: Anthropic's current docs describe the same while stop_reason == "tool_use" loop.
A real example
Building its coding agent for SWE-bench tasks, Anthropic found the model "would make mistakes with tools using relative filepaths after the agent had moved out of the root directory." The fix was in the tool, not the prompt: they "changed the tool to always require absolute filepaths", and the model then used it "flawlessly". They "spent more time optimizing our tools than the overall prompt."
"High-level flow of a coding agent", from Anthropic's "Building effective agents" (2024-12-19). From anthropic.com, 30 October 2026.
Where it goes wrong
The key ends up in the browser. Anthropic's TypeScript SDK refuses to run in a web browser by default, "to avoid exposing your secret API credentials." In January 2024 a developer asked for a way round it in issue #248, and an SDK contributor closed it as not planned, saying "Anthropic continues to have no plans to change this". In August 2024 the SDK shipped the switch, named dangerouslyAllowBrowser, which adds a header called anthropic-dangerous-direct-browser-access. The names say what it costs.
The key ends up on GitHub. Anthropic's help article names accidental exposure in public code repos as one of the most frequent causes of leaked keys. GitHub scans public repos for Claude keys, and Anthropic "automatically deactivates the exposed API key." Keep the key in a .env file listed in .gitignore.
A tool call is left unanswered. Each tool_use block needs a tool_result in the next message, or the API refuses the request with "tool_use ids were found without tool_result blocks immediately after". In April 2026, an issue on Letta's tracker reported an agent whose run crashed mid-way, leaving tool calls in its saved history with no results. After that, "every subsequent message hits the same orphaned tool_use in history".
The loop can run away. This one is a warning in Anthropic's docs, not a reported failure. Anthropic warns that agents mean "higher costs, and the potential for compounding errors", and notes it's common to add "stopping conditions (such as a maximum number of iterations)". The Agent SDK has max_turns for this. Without it, the loop runs until Claude finishes on its own.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), run Anthropic's loop in api/scripts/agent_loop.py with your own key. Here's how:
Create a key in the Claude Console and put ANTHROPIC_API_KEY=... in api/.env. Check that .env is in .gitignore before you commit anything. In api/, run pip install anthropic python-dotenv.
In scripts/agent_loop.py, call load_dotenv(), then copy the tutorial's loop with one tool, list_classes, that returns two made-up yoga classes as JSON. Cap the while loop at 5 turns, so a runaway loop stops.
Ask: "Which class on Monday has space?" Print response.stop_reason on each turn. You should see tool_use, then end_turn.
Keep this script out of web/. The TypeScript website should never see the key.
From snapshot/web/platform.claude.com/docs-en-agents-and-tools-tool-use-build-a-tool-using-agent.md, line 21: “When Claude determines that a tool call is needed, the response comes back with stop_reason: "tool_use" and a tool_use content block containing the tool name, a unique id, and the structured input. Your code runs the tool, then sends the result back in a tool_result block whose tool_use_id matches the id from the call.”
From snapshot/web/youtube.com/watch-v-qfhioco-ko.md, lines 102–104: “Another weird constraint of LLMs is LLMs are kind of like the guy from Memento, right? [07:31] They just continually forget. [07:32] They could just keep resetting back to the base state.”
From snapshot/web/anthropic.com/engineering-building-effective-agents.md, lines 22–25: “draw an important architectural distinction between workflows and agents: - Workflows are systems where LLMs and tools are orchestrated through predefined code paths. - Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.”
From snapshot/web/anthropic.com/engineering-building-effective-agents.md, line 234: “While building our agent for SWE-bench, we actually spent more time optimizing our tools than the overall prompt. For example, we found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory. To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly.”
From snapshot/web/github.com/letta-ai-letta-issues-3308.md, line 47: “When a run crashes or times out mid-tool-sequence, tool_use blocks can be stored in conversation history without their matching tool_result blocks. On the next request, Anthropic rejects the entire conversation with a 400 error.”
