AI Agent Project for Beginners: Build a Tool-Using Agent in Python From Scratch

How to build an AI agent in Python, step by step

1. Step 1. Set up the project

   Create a folder, a virtual environment and install one package.

   mkdir ai-agent && cd ai-agent
   python -m venv .venv
   # Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
   pip install openai
   mkdir notes

   Put two or three small .txt files in the notes folder, for example exam dates or a reading list. Set two environment variables: OPENAI_API_KEY with your key, and LLM_MODEL with any current tool-calling model from your provider's documentation. Never paste the key into code you upload to GitHub.

2. Step 2. Write the three tools

   Tools are ordinary Python functions that take simple arguments and return a string. Each one is written defensively, because the model, not you, chooses the inputs.

   # tools.py
   import ast, json, operator, urllib.parse, urllib.request
   from pathlib import Path
   
   OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
          ast.Div: operator.truediv, ast.Pow: operator.pow, ast.USub: operator.neg}
   
   def calculator(expression: str) -> str:
       def ev(node):
           if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
               return node.value
           if isinstance(node, ast.BinOp) and type(node.op) in OPS:
               return OPS[type(node.op)](ev(node.left), ev(node.right))
           if isinstance(node, ast.UnaryOp) and type(node.op) in OPS:
               return OPS[type(node.op)](ev(node.operand))
           raise ValueError("only numbers and + - * / ** are allowed")
       return str(ev(ast.parse(expression, mode="eval").body))
   
   def wikipedia_summary(topic: str) -> str:
       title = urllib.parse.quote(topic.replace(" ", "_"))
       url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
       req = urllib.request.Request(url, headers={"User-Agent": "student-agent/0.1"})
       with urllib.request.urlopen(req, timeout=10) as r:
           return json.load(r).get("extract", "No summary found.")
   
   NOTES = Path("notes").resolve()
   
   def read_file(name: str) -> str:
       path = (NOTES / name).resolve()
       if path.parent != NOTES or path.suffix != ".txt":
           return "Error: only .txt files inside the notes folder can be read."
       return path.read_text(encoding="utf-8")[:4000]

   The calculator walks the expression tree instead of calling eval, so an input like an import statement is rejected. The file reader resolves the path and refuses anything outside the notes folder, which blocks tricks such as ../../ paths.

3. Step 3. Describe the tools to the model

   The model only knows what your tool descriptions tell it. Each tool needs a name, a one-line description of when to use it, and its parameters as JSON Schema.

   # agent.py
   import json, os
   from openai import OpenAI
   from tools import calculator, wikipedia_summary, read_file
   
   client = OpenAI()  # reads OPENAI_API_KEY from the environment
   MODEL = os.environ.get("LLM_MODEL", "gpt-4o-mini")  # any current tool-calling model
   
   def fn(name, description, param, param_desc):
       return {"type": "function", "function": {
           "name": name, "description": description,
           "parameters": {"type": "object",
                          "properties": {param: {"type": "string", "description": param_desc}},
                          "required": [param]}}}
   
   TOOLS = [
       fn("calculator", "Do arithmetic. Use for any maths.", "expression", "e.g. 18 * 4.5"),
       fn("wikipedia_summary", "Get facts about a person, place or topic.", "topic", "Wikipedia article title"),
       fn("read_file", "Read one of the user's .txt notes.", "name", "file name, e.g. exams.txt"),
   ]
   REGISTRY = {"calculator": calculator, "wikipedia_summary": wikipedia_summary, "read_file": read_file}

   Good descriptions do most of the work. If the agent picks the wrong tool, improve the description before you touch anything else.

4. Step 4. Write the agent loop with a step limit

   The loop sends the conversation, runs any tool calls, appends each result as a "tool" message with the matching tool_call_id, and stops at max_steps.

   # agent.py (continued)
   SYSTEM = ("You are a helpful agent. Use a tool whenever it helps. "
             "Never guess numbers or facts you can look up. Answer briefly.")
   
   def run_agent(task, max_steps=5):
       messages = [{"role": "system", "content": SYSTEM},
                   {"role": "user", "content": task}]
       for step in range(1, max_steps + 1):
           reply = client.chat.completions.create(
               model=MODEL, messages=messages, tools=TOOLS)
           msg = reply.choices[0].message
           if not msg.tool_calls:           # no tool requested: final answer
               return msg.content
           messages.append(msg)             # keep the model's tool request
           for call in msg.tool_calls:
               name, args = call.function.name, {}
               try:
                   args = json.loads(call.function.arguments or "{}")
                   tool = REGISTRY.get(name)
                   result = tool(**args) if tool else f"Error: unknown tool {name}"
               except Exception as e:       # bad arguments or a failing tool
                   result = f"Error: {e}"
               print(f"  step {step}: {name}({args}) returned {str(result)[:80]}")
               messages.append({"role": "tool", "tool_call_id": call.id,
                                "content": str(result)})
       return "Stopped: reached the step limit without a final answer."
   
   if __name__ == "__main__":
       print(run_agent(input("Task: ")))

   Two details matter. First, every tool call must get exactly one "tool" message back with its id, or the API rejects the next request. Second, errors are returned to the model as text instead of crashing, so the agent can read "Error: ..." and try something else.

5. Step 5. Run it and read the trace

   Run python agent.py and try tasks that need zero, one and several tools:

   • "What is 17.5 percent of 2,340?" (calculator only)
   • "Where is ISRO headquartered?" (Wikipedia only)
   • "How many days are left between the two exam dates in exams.txt?" (file, then calculator)
   • "Say hello." (no tool at all)

   Watch the printed trace. The step lines show which tool the model picked, with what arguments, and what came back. Reading traces is the most important debugging skill for agents: when an answer is wrong, the trace tells you whether the model chose the wrong tool, passed bad arguments, or misread a correct result.

6. Step 6. Add guardrails before you add tools

   Guardrails are the rules your code enforces no matter what the model asks for. You already have four: a step limit, a tool allowlist (REGISTRY), a sandboxed file path, and no eval. Add a human check before any tool that changes something:

   RISKY = {"write_file", "send_email"}
   
   def approved(name, args):
       if name not in RISKY:
           return True
       answer = input(f"Agent wants to run {name} with {args}. Allow? (y/n) ")
       return answer.strip().lower() == "y"

   Call approved(name, args) inside the loop before running a tool, and return "Error: the user declined" when it is False. Also cap tool output length (the file reader already cuts at 4,000 characters) so one huge result cannot flood the context. Read more on AI guardrails.

7. Step 7. Test the agent and measure it

   Write 15 tasks with known answers: 5 that need no tool, 5 that need one tool, and 5 that need two. Run each one and record four things in a spreadsheet:

   1. Right tool chosen: did it call the tools you expected?
   2. Correct answer: was the final answer right?
   3. Steps used: how many loop steps did it take?
   4. Hit the limit: did it ever stop at max_steps?

   Your report line then reads like "correct tool choice 14 of 15, correct answers 13 of 15, average 2.1 steps, 0 step-limit stops". Run the same tasks with two different models by changing LLM_MODEL, and you have a comparison table most student projects do not have.

Frequently asked questions

Keep learning

References

• OpenAI documentation: function calling
• Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models (arXiv)
• Python documentation: ast module
• Wikimedia REST API documentation