如何用纯 Python 从零构建 AI 智能体

In this article, you will learn what an AI agent is and how to build one from scratch in plain Python using the Anthropic API, without relying on any orchestration framework.

Topics we will cover include:

• Why tool calling is necessary and how to define a tool the model can use.
• How to implement the request-execute-respond loop that drives an agent’s behavior.
• How to add persistent memory so the agent maintains context across multiple turns.

Introduction

A simple call to a large language model is enough when the answer can be produced from what the model already knows: explaining a policy, drafting a reply, summarizing text. It is not enough once the answer depends on data outside that training set, such as a live order status or a row in your database; this gap is what an agent is built to close.

An AI agent is what results once the model can call out to something else — a function, a database query, an API — and use the result before it answers. Reaching for an agent orchestration framework to get this working is a reasonable move, eventually.

Writing one from scratch in plain Python, using a raw API call, makes the underlying architecture clear. At its core, there is simply a model, a loop that manages the interaction, and a small set of well-defined functions that give the model the capabilities it needs. Stripping away the frameworks and abstractions makes it easier to see how these pieces fit together and what is actually happening under the hood.

This article covers:

• Why tool calling is necessary and what you need installed to try it
• How to describe a tool so the model knows when and how to call it
• What the request-execute-respond loop looks like in code
• How to add memory so the agent keeps context across turns

You can find the companion code for this article in this GitHub repository.

Prerequisites

You need Python 3.10 or later, an Anthropic API key, and the Anthropic Python SDK:

Set your key as an environment variable so the client picks it up without hardcoding it anywhere:

This is all you need to get started. You can find all the code in the agent.py script.

⚠️ A note to readers: Anthropic will officially retire Claude Sonnet 4.5 on November 30, 2026. If you are following this tutorial after that date, the specific model code used in these examples will no longer work. To ensure your project runs smoothly, replace the model string in the API calls with a newer version or the latest available model.

Setting Up the Model Call

A minimal wrapper around the API is a function that sends a prompt and returns text:

This handles a large share of questions well — explaining a policy, drafting a reply, summarizing a paragraph. It fails the moment the answer depends on data the model was never shown. Ask ask("What is the status of order #4471?") and the model has no mechanism to check: that information lives in your database, not in its training data. It either states that it does not know, or produces a plausible answer anyway, and no amount of prompting changes that, since no prompt grants the model access to data it was never given. Tool calling gives the model a defined way to request that data instead of inferring it.

Read The Roadmap to Mastering Tool Calling in AI Agents to learn more.

Defining a Tool the Model Can Ask For

Giving the model access to a function means writing the function, and writing a description of it that the model can read. The description matters because it tells the model what the function does and when to reach for it.

The schema is structured metadata: a name, a description, and a definition of the parameters the function expects. Tool use works the same way across most providers: you pass the model a list of these schemas alongside your message, and the model decides on its own whether answering the question requires calling one of them.

Executing the Tool and Feeding the Result Back

Pass the schema in, and something different happens. Instead of a plain text answer, the response comes back with a stop_reason of tool_use and a content block describing which function the model wants to call and with what arguments. The model has not run anything yet — it is paused, and has returned a request for you to act on.

Two round trips happen here. The first asks the model what it wants to do. You run the function yourself — the lookup against orders_db, or in a production system, a call to your order service — append the result back into the conversation as a tool_result, and send everything again. The second round trip is where the model reads that result and gives you an answer grounded in it, instead of a guess.

Looping Until the Model Has What It Needs

This pattern generalizes once you stop hardcoding a single tool and a single round trip. A more complex question might need two or three tool calls in sequence — look up the order, then check the shipping carrier’s tracking API, then format a reply — and you will not know the number in advance. So instead of writing out each step, you loop until the model stops asking for tools.

The max_iterations cap prevents a specific failure: without it, a model that keeps deciding it needs “one more” tool call will loop until you run out of budget or patience. Capping the loop and returning a clear fallback message is a small line of code that saves you from a confusing incident in production.

Strip away the surrounding code and this is the whole idea: a model, a loop, and a set of functions it can ask you to run. Nothing here is specific to order lookups. You can swap in a search call, an internal API, or a query of your own, and the same loop handles it, as long as the schema describes it clearly.

Adding Memory

run_agent as written forgets everything the moment it returns. Call it twice in a row — first asking about order #4471, then asking “and when will it arrive?” — and the second call has no idea what “it” refers to, because each call builds a brand new messages list from scratch. Memory here means keeping that list around between calls instead of discarding it.

The simplest way to do that is to stop passing messages in fresh each time and start keeping it on an object instead:

self.messages persists across calls to run(), so the model sees the full conversation each time, including the earlier tool call and its result. Ask about order #4471, then ask “and when will it arrive?”, and the model can resolve “it” from the history already sitting in self.messages.

This covers memory within a single running process. It does not cover what happens once that list grows past the model’s context window, or what happens if the process restarts and self.messages resets to empty. Those are real constraints of this approach, and they are the reason production agents usually add a step that trims or summarizes older turns, along with a place to persist the conversation outside the process itself — a database row, a file, a cache key tied to a session ID.

Summary and Next Steps

What exists at this point is a model call, a tool schema describing a function, a loop that executes tool calls until the model has enough information to answer, and a class that keeps the conversation across turns. That is a working agent, and every piece of it is code you wrote and can read back line by line.

Here are a few directions worth exploring from here:

• Testing which tool the model picks once there are several competing for the same question
• Persisting and trimming conversation history so it does not overflow the context window
• Handling a failing tool call, such as a timeout or a bad response from an upstream API, so it does not crash the loop
• Adding logging around each tool call for debugging and later review

Happy building!

No comments yet.