🤖 Build an AI Agent

What an agent actually is

Strip away the buzzwords and an AI agent is a simple loop:

A plain chatbot answers in one shot. An agent loops: it can look something up, do a calculation, then use those results to answer. That loop, plus tools and memory, is the whole idea.

The loop keeps cycling until the model has enough to answer.

Step 1: Set up

Create a project and install one small library. We will talk to an OpenAI-compatible API (Groq's free tier here).

mkdir my-agent && cd my-agent
python -m venv venv
# Windows: venv\Scripts\activate   |   Linux/Mac: source venv/bin/activate
pip install openai

Get a free key from console.groq.com/keys and set it as an environment variable so it never lives in your code:

# Windows (PowerShell)
$env:GROQ_API_KEY="your_key_here"

# Linux / macOS
export GROQ_API_KEY="your_key_here"

Step 2: Talk to the model

First, the simplest possible call. Save this as agent.py:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.groq.com/openai/v1",
    api_key=os.environ["GROQ_API_KEY"],
)

resp = client.chat.completions.create(
    model="llama-3.1-8b-instant",
    messages=[{"role": "user", "content": "Say hi in one sentence."}],
)
print(resp.choices[0].message.content)

Run python agent.py. If you see a friendly sentence, your model connection works. Everything else builds on this.

Step 3: Give it a tool

Tools are just Python functions the model is allowed to call. Let us give it a calculator (LLMs are famously bad at arithmetic, so this is a perfect first tool).

def calculator(expression: str) -> str:
    """Safely evaluate a simple math expression."""
    try:
        return str(eval(expression, {"__builtins__": {}}, {}))
    except Exception as e:
        return f"error: {e}"

tools = [{
    "type": "function",
    "function": {
        "name": "calculator",
        "description": "Evaluate a math expression like '23 * 47'.",
        "parameters": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
        },
    },
}]

You describe the tool to the model in plain words. The model decides when to call it, you decide what it does.

Step 4: Build the loop

This is the heart of an agent: keep calling the model, and whenever it asks for a tool, run it and hand back the result, until it produces a final answer.

import json

def run_agent(question: str) -> str:
    messages = [{"role": "user", "content": question}]
    while True:
        resp = client.chat.completions.create(
            model="llama-3.1-8b-instant",
            messages=messages,
            tools=tools,
        )
        msg = resp.choices[0].message
        messages.append(msg)

        if not msg.tool_calls:
            return msg.content          # final answer, we are done

        for call in msg.tool_calls:     # the model wants a tool
            args = json.loads(call.function.arguments)
            result = calculator(**args)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })

print(run_agent("What is 1234 * 5678, and is it bigger than 7 million?"))

Watch what happens: the model calls calculator, reads the number, then answers the comparison in words. That two-step reasoning is the agent loop working.

Step 5: Add memory

Right now each question starts fresh. "Memory" is just keeping the messages list between turns so the agent remembers the conversation.

history = []

def chat(question: str) -> str:
    history.append({"role": "user", "content": question})
    # ... run the same loop, but start from `history` instead of a new list,
    #     and append the final answer back to `history`.
    # Now the agent recalls earlier turns.
    return "..."

That is the difference between a goldfish and an assistant. For longer memory, you would store past messages in a database or summarize old ones, but the idea stays this simple.

Step 6: Make it a real project

Now turn the toy into something you would actually show. Swap the calculator for a tool that matters to you:

• A research agent - add a web-search tool and have it summarize findings.
• A coding helper - a tool that reads files from a folder and answers questions about your code.
• A personal assistant - tools for weather, reminders, or a to-do list.
• A data agent - a tool that runs SQL against a small database (pairs with the SQL guide).

Add 2 to 3 tools, give it a clear system prompt describing its job, wrap it in a simple command-line or web chat, and you have a portfolio-worthy project.

Going further

Once the from-scratch version makes sense, these frameworks do the plumbing for you (but you will understand what they are doing):

Concepts to explore next: RAG (let the agent search your documents), multi-agent setups (agents that talk to each other), and guardrails (keeping tools safe). This whole site's own AI helper is a small agent-style system, you now know roughly how it works.

Copy-paste AI prompts

Do not build alone. Paste these into any AI chatbot (or this site's ✦ Ask AI) to speed up each step. Tweak the bracketed parts.

Act as a senior Python engineer. Write a minimal AI agent from scratch using the
OpenAI Python SDK against an OpenAI-compatible endpoint. It should: (1) call an LLM,
(2) support one tool called "calculator", (3) run a think-act-observe loop until a
final answer. Keep it under 60 lines, well commented, no frameworks. Explain each part.

I want to add a tool to my AI agent that [does X, e.g. "searches my notes folder"].
Give me: the Python function, the JSON tool schema the model needs, and a one-line
description that helps the model know when to call it. Keep it safe and simple.

My agent calls the tool but crashes on the tool result. Here is my code and the
error: [paste code + error]. Explain the root cause in plain words, then give the
minimal fix. Do not rewrite everything.

Help me turn my basic agent into a portfolio project: [describe your idea]. Suggest
2-3 useful tools, a clear system prompt describing the agent's job, and a simple way
to demo it (CLI or minimal web page). Keep it achievable in a weekend.

What to do next