{"id":21657,"date":"2026-08-14T00:35:16","date_gmt":"2026-08-13T22:35:16","guid":{"rendered":"https:\/\/www.juust.org\/?p=21657"},"modified":"2026-08-14T00:35:23","modified_gmt":"2026-08-13T22:35:23","slug":"an-example-agent-in-python","status":"publish","type":"post","link":"https:\/\/www.juust.org\/index.php\/an-example-agent-in-python\/2026\/08\/","title":{"rendered":"An Example Agent in Python"},"content":{"rendered":"\n

Build an AI Agent from Scratch \u2014 No Framework, Just Python<\/p>\n\n\n\n

If you can read a while<\/code> loop, you can understand every line of an agent.<\/em><\/p>\n\n\n\n

Frameworks like LangChain, CrewAI and AutoGen are great for shipping but terrible for learning<\/em>. When you write Agent(executor=\u2026).run()<\/code>, a black box makes a hundred design decisions for you and hides every single one. The surprising truth? There is no deep machinery inside that box<\/strong>. The whole “agent” idea fits in a single while<\/code> loop.<\/p>\n\n\n\n

This article builds that loop from scratch: a real, working AI agent you can talk to, that calculates, reads files and searches the web \u2014 and you will understand every<\/em> line. No abstractions. No frameworks. Just Python, the OpenAI API, and ~300 lines of code.<\/p>\n\n\n\n

By the end you will also see how two of these agents, each with a different personality, can negotiate against each other in a game. Everything is in github.com\/juustesout\/python-agents-example<\/a>.<\/p>\n\n\n\n

\n\n\n\n

1. Installatie & Setup<\/h2>\n\n\n\n

The agent uses the OpenAI Chat Completions API, duckduckgo-search for web lookups, and python-dotenv<\/code> to load secrets. That is the entire<\/em> dependency list.<\/p>\n\n\n\n

# requirements.txt\nopenai>=1.40.0\npython-dotenv>=1.0.0\nddgs>=9.0.0\n<\/code><\/pre>\n\n\n\n
Clone the repo and create a virtual environment:<\/p>\n\n\n\n
git clone https:\/\/github.com\/juustesout\/python-agents-example.git\ncd python-agents-example\npython -m venv .venv\nsource .venv\/bin\/activate       # Linux\/macOS\n# .venv\\Scripts\\activate        # Windows\npip install -r requirements.txt\n<\/code><\/pre>\n\n\n\n
API keys in .env<\/h3>\n\n\n\n
Copy the example env file and add your OpenAI key:<\/p>\n\n\n\n
cp .env.example .env\n<\/code><\/pre>\n\n\n\n
Open .env<\/code> and set:<\/p>\n\n\n\n
OPENAI_API_KEY=sk-proj-your-key-here\nOPENAI_MODEL=gpt-4o-mini        # optional, this is the default\nAGENT_VERBOSE=1                 # set to 0 to silence trace output\n<\/code><\/pre>\n\n\n\n
The .gitignore<\/code> already has **\/.env<\/code> so your key stays local. python-dotenv<\/code> loads the file automatically when the agent starts \u2014 you never have to export<\/code> anything.<\/p>\n\n\n\n
\n\n\n\n
2. Project Structure<\/h2>\n\n\n\n
The repo is deliberately flat. Two examples, one shared core:<\/p>\n\n\n\n
python-agents-examples\/\n\u251c\u2500\u2500 01_mini_agent\/\n\u2502   \u251c\u2500\u2500 agent.py          # The core loop + 3 built-in tools\n\u2502   \u251c\u2500\u2500 demo.py           # Entry point with example prompts\n\u2502   \u2514\u2500\u2500 sample.txt        # A test file for the file reader tool\n\u251c\u2500\u2500 02_agent_vs_agent\/\n\u2502   \u2514\u2500\u2500 game.py           # Two agents with opposing personalities negotiate\n\u251c\u2500\u2500 .env.example          # Copy to .env, add your key\n\u2514\u2500\u2500 requirements.txt\n<\/code><\/pre>\n\n\n\n
01_mini_agent<\/strong> is a complete, single-file agent (~190 lines of real code wrapped in ~500 lines of comments). You can read it in one sitting and understand every line.<\/p>\n\n\n\n
02_agent_vs_agent<\/strong> instantiates the exact same MiniAgent<\/code> class twice \u2014 the only difference is the system prompt \u2014 and drops them into a turn-based negotiation game over $100.<\/p>\n\n\n\n
\n\n\n\n
3. The Core Loop \u2014 How Every Agent Works<\/h2>\n\n\n\n
Here is the whole trick, in four steps:<\/p>\n\n\n\n
    \n
  1. The model receives the full conversation history<\/strong> plus a list of tool schemas<\/strong> (name, description, expected JSON arguments).<\/li>\n\n\n\n
  2. The model replies with either plain text or<\/em> a structured tool call like {\"name\": \"calculator\", \"arguments\": {\"expression\": \"2 ** 10\"}}<\/code>.<\/li>\n\n\n\n
  3. If it is a tool call, you<\/strong> \u2014 not the framework, not the model \u2014 run the matching Python function and append the result as a role=\"tool\"<\/code> message.<\/li>\n\n\n\n
  4. Repeat from step 1 until the model returns plain text. That text is the final answer.<\/li>\n<\/ol>\n\n\n\n
    That is it. The loop model \u2192 tool \u2192 result \u2192 model \u2192 \u2026 \u2192 answer<\/strong> is the entire idea behind every agent framework ever built.<\/p>\n\n\n\n
    The MiniAgent class<\/h3>\n\n\n\n
    The agent is built around three things: a list of messages<\/code>, a registry of tools<\/code>, and a lazy OpenAI client. No hidden state, no bookkeeping.<\/p>\n\n\n\n
    class MiniAgent:\n    def __init__(self, system_prompt, model=None,\n                 temperature=0.7, max_tool_iters=10, verbose=True):\n        self.messages = []           # the only \"memory\" \u2014 a list of JSON dicts\n        self.tools = {}              # name -> Tool registry\n        self._client = None          # lazy OpenAI client\n        ...\n<\/code><\/pre>\n\n\n\n
    The run()<\/code> method \u2014 the heart<\/h3>\n\n\n\n
    This is the loop that makes the agent “agentic”:<\/p>\n\n\n\n
    def run(self, user_prompt, *, reset=True):\n    if reset or not self.messages:\n        # Fresh conversation: system prompt + user message\n        self.messages = [\n            {\"role\": \"system\", \"content\": self.system_prompt},\n            {\"role\": \"user\", \"content\": user_prompt},\n        ]\n    else:\n        # Continue existing conversation (the \"memory\" trick)\n        self.messages.append({\"role\": \"user\", \"content\": user_prompt})\n\n    for iteration in range(1, self.max_tool_iters + 1):\n        reply = self._call_model()           # send history + tool schemas\n\n        if reply.tool_calls:\n            self._handle_tool_calls(reply.tool_calls)  # execute tools\n            continue                                   # loop back\n\n        # No tool calls \u2192 final answer\n        self.messages.append({\"role\": \"assistant\", \"content\": reply.content})\n        return reply.content\n\n    raise RuntimeError(f\"No answer after {self.max_tool_iters} iterations.\")\n<\/code><\/pre>\n\n\n\n
    Every iteration prints a trace in color so you can literally watch the agent think, call a tool, read the result, and decide what to do next \u2014 in real time.<\/p>\n\n\n\n
    How _call_model()<\/code> works<\/h3>\n\n\n\n
    The agent converts its tool registry into OpenAI’s JSON schema format and sends it alongside the conversation:<\/p>\n\n\n\n
    def _call_model(self):\n    tool_schemas = [tool.to_openai_schema()\n                    for tool in self.tools.values()]\n    response = self._client.chat.completions.create(\n        model=self.model,\n        messages=self.messages,\n        tools=tool_schemas or None,\n        tool_choice=\"auto\" if tool_schemas else None,\n    )\n    return response.choices[0].message\n<\/code><\/pre>\n\n\n\n
    Key insight:<\/strong> a “tool schema” is just a plain JSON object describing a Python function. The model does not<\/em> run anything \u2014 it only requests<\/strong> a call. You run it.<\/p>\n\n\n\n
    How tool results get back into context<\/h3>\n\n\n\n
    This is where the API contract gets specific. The assistant message carrying the tool call must be appended before<\/em> the results, and every result must include the matching tool_call_id<\/code>:<\/p>\n\n\n\n
    def _handle_tool_calls(self, tool_calls):\n    # 1. Record the assistant message with the tool call requests\n    self.messages.append({\n        \"role\": \"assistant\",\n        \"content\": None,\n        \"tool_calls\": [\n            {\"id\": call.id, \"type\": \"function\",\n             \"function\": {\"name\": call.function.name,\n                          \"arguments\": call.function.arguments}}\n            for call in tool_calls\n        ],\n    })\n\n    # 2. Execute each tool and append its result\n    for call in tool_calls:\n        result = self._execute_tool(call.function.name,\n                                    call.function.arguments)\n        self.messages.append({\n            \"role\": \"tool\",\n            \"tool_call_id\": call.id,\n            \"content\": result,\n        })\n<\/code><\/pre>\n\n\n\n
    This is where most home-grown agents fail: the API will reject your next request unless role=\"tool\"<\/code> messages are correctly paired with the tool_call_id<\/code> from the assistant message.<\/p>\n\n\n\n
    \n\n\n\n
    4. Tools \u2014 Just Python Functions with a JSON Schema<\/h2>\n\n\n\n
    A tool is nothing more than a Python function plus metadata. The Tool<\/code> class bundles them together:<\/p>\n\n\n\n
    @dataclass\nclass Tool:\n    name: str\n    description: str\n    parameters: dict       # JSON Schema\n    func: Callable[..., str]\n\n    def to_openai_schema(self):\n        return {\n            \"type\": \"function\",\n            \"function\": {\n                \"name\": self.name,\n                \"description\": self.description,\n                \"parameters\": self.parameters,\n            },\n        }\n<\/code><\/pre>\n\n\n\n
    When the model calls a tool, _execute_tool<\/code> looks it up in the registry, parses the JSON arguments and calls the function:<\/p>\n\n\n\n
    def _execute_tool(self, name, arguments_json):\n    tool = self.tools.get(name)\n    args = json.loads(arguments_json or \"{}\")\n    result = tool.func(**args)      # Just a Python call!\n    return str(result)\n<\/code><\/pre>\n\n\n\n
    That is it.<\/strong> Swapping a tool for a different API is a one-line change. Adding a new tool is one function, one schema and one call to agent.add_tool()<\/code>.<\/p>\n\n\n\n
    Tool 1: Calculator (safe evaluation with ast<\/code>)<\/h3>\n\n\n\n
    The calculator is a great example of why eval()<\/code> is dangerous and ast<\/code> is safe. The model could trick eval(\"__import__('os').system('rm -rf \/')\")<\/code> but ast<\/code> only allows whitelisted node types:<\/p>\n\n\n\n
    def calculator(expression: str) -> str:\n    bin_ops = {\n        ast.Add: operator.add, ast.Sub: operator.sub,\n        ast.Mult: operator.mul, ast.Div: operator.truediv,\n        ast.FloorDiv: operator.floordiv, ast.Mod: operator.mod,\n        ast.Pow: operator.pow,\n    }\n    constants = {\"pi\": math.pi, \"e\": math.e}\n\n    def evaluate(node):\n        if isinstance(node, ast.Constant):\n            if isinstance(node.value, (int, float)):\n                return node.value\n            raise ValueError(\"only numbers allowed\")\n        if isinstance(node, ast.Name):\n            if node.id in constants:\n                return constants[node.id]\n            raise ValueError(f\"unknown constant '{node.id}'\")\n        if isinstance(node, ast.BinOp):\n            op = bin_ops.get(type(node.op))\n            return op(evaluate(node.left), evaluate(node.right))\n        if isinstance(node, ast.UnaryOp):\n            op = unary_ops.get(type(node.op))\n            return op(evaluate(node.operand))\n        raise ValueError(f\"construct {type(node).__name__} disallowed\")\n\n    tree = ast.parse(expression, mode=\"eval\")\n    return str(evaluate(tree.body))\n<\/code><\/pre>\n\n\n\n
    The whitelist is the safety mechanism. The AST can only contain node types that have a handler in evaluate()<\/code>. Any other construct \u2014 function calls, imports, attribute access \u2014 raises before it can execute.<\/p>\n\n\n\n
    Tool 2: Safe file reader (path traversal defence)<\/h3>\n\n\n\n
    Reading a file seems simple until the model tries ..\/..\/etc\/passwd<\/code>. The guard is Path.resolve()<\/code> combined with is_relative_to()<\/code>:<\/p>\n\n\n\n
    def read_local_file(filepath: str) -> str:\n    base = _DEFAULT_BASE_DIR.resolve()          # e.g. \/home\/user\/project\/\n    target = (base \/ filepath).resolve()        # resolve .. and symlinks\n\n    if not target.is_relative_to(base):         # escaped the sandbox?\n        return \"Error: path traversal blocked.\"\n    if not target.is_file():\n        return \"Error: file not found.\"\n    if target.stat().st_size > _MAX_FILE_BYTES:\n        return \"Error: file too large.\"\n\n    return target.read_text(encoding=\"utf-8\", errors=\"replace\")\n<\/code><\/pre>\n\n\n\n
    is_relative_to()<\/code> is the key. Even if the model constructs a path like ..\/..\/..\/..\/etc\/passwd<\/code>, after resolve()<\/code> the absolute path falls outside<\/em> base<\/code> and the tool refuses.<\/p>\n\n\n\n
    Tool 3: Web search (zero-API-key via DuckDuckGo)<\/h3>\n\n\n\n
    DuckDuckGo’s search API requires no key at all. The agent tries two import paths (the package was renamed from duckduckgo_search<\/code> to ddgs<\/code>):<\/p>\n\n\n\n
    try:\n    from ddgs import DDGS\nexcept ImportError:\n    try:\n        from duckduckgo_search import DDGS\n    except ImportError:\n        DDGS = None\n\ndef web_search(query: str, max_results: int = 5) -> str:\n    if DDGS is None:\n        return \"Error: install duckduckgo-search package.\"\n\n    results = list(DDGS().text(query, max_results=max_results))\n    return \"\\n\\n\".join(\n        f\"{i}. {r['title']}\\n   {r['href']}\\n   {(r.get('body') or '')[:200]}\"\n        for i, r in enumerate(results, start=1)\n    )\n<\/code><\/pre>\n\n\n\n
    Swap DuckDuckGo for SerpAPI, Tavily or Google Search in one line \u2014 the tool interface never changes, only the implementation.<\/p>\n\n\n\n
    Registering tools on the agent<\/h3>\n\n\n\n
    Every tool gets added through a single method that expects a name, description, JSON schema and the Python function:<\/p>\n\n\n\n
    agent.add_tool(\n    name=\"calculator\",\n    description=\"Evaluate a math expression. Supports + - * \/ \/\/ % ** pi e.\",\n    parameters={\n        \"type\": \"object\",\n        \"properties\": {\n            \"expression\": {\n                \"type\": \"string\",\n                \"description\": \"The expression to evaluate.\",\n            }\n        },\n        \"required\": [\"expression\"],\n    },\n    func=calculator,\n)\n<\/code><\/pre>\n\n\n\n
    Three tools, three calls. The pattern is identical for every tool you will ever add.<\/p>\n\n\n\n
    \n\n\n\n
    5. Running the Agent<\/h2>\n\n\n\n
    The demo runner at 01_mini_agent\/demo.py<\/code> exercises all three tools with built-in prompts:<\/p>\n\n\n\n
    # Default: runs the four built-in demo prompts\npython 01_mini_agent\/demo.py\n\n# Custom prompt\npython 01_mini_agent\/demo.py \"What is the speed of light times 3600?\"\n<\/code><\/pre>\n\n\n\n
    Example session (real output, real agent):<\/p>\n\n\n\n
    USER: What is 2 ** 10 + 1000? Use the calculator.\n\n[agent] iteration 1: calling the model...\n[agent]   -> calculator({\"expression\": \"2 ** 10 + 1000\"})\n[agent]   <- result: '2024'\n[agent] iteration 2: calling the model...\n[agent] final answer received.\n\nFINAL ANSWER: The result of 2^10 + 1000 is 2024.\n\n---\n\nUSER: Search the web for the speed of light, then\n       calculate how far it travels in one hour.\n\n[agent] iteration 1: calling the model...\n[agent]   -> web_search({\"query\": \"speed of light\"})\n[agent]   <- result: '1. Speed of light\\n ...\n                       299,792,458 m\/s'\n[agent] iteration 2: calling the model...\n[agent]   -> calculator({\"expression\": \"299792458 * 3600\"})\n[agent]   <- result: '1079252848800'\n[agent] iteration 3: calling the model...\n[agent] final answer received.\n\nFINAL ANSWER: Light travels approximately 1.08 trillion meters\n             (1,079,252,848,800 m) in one hour.\n<\/code><\/pre>\n\n\n\n
    The trace is the loop. You see every model call, every tool execution and every intermediate result. That transparency is the whole point of building from scratch \u2014 no black box, no surprises.<\/p>\n\n\n\n
    \n\n\n\n
    6. Two Agents, One Conversation: Multi-Agent Negotiation<\/h2>\n\n\n\n
    \"\"<\/a><\/figure>\n\n\n\n
    If one agent is a while-loop, multi-agent is just two copies of the same loop<\/strong> talking to each other. The “agent vs. agent” example at 02_agent_vs_agent\/game.py<\/code> is the cleanest example of that.<\/p>\n\n\n\n
    Two instances of MiniAgent<\/code>, one system prompt each, take turns proposing a split of $100:<\/p>\n\n\n\n
    POT = 100              # dollars to split\nMAX_TURNS = 8          # before the game is called off\n\nalice = MiniAgent(\n    system_prompt=\"You are ALICE, the Rational Negotiator<\/strong>. ...\",\n    temperature=0.6, verbose=False)\n\nbob = MiniAgent(\n    system_prompt=\"You are BOB, the Bold Trader<\/strong>. ...\",\n    temperature=0.6, verbose=False)\n<\/code><\/pre>\n\n\n\n
    The two prompts are the only<\/em> difference. Alice is instructed to be fair, evidence-driven and principled. Bob is told to bluff, use pressure tactics and maximise his share. Same code, different personality \u2014 which tells you everything about what “personality” really is in an AI agent: just text.<\/p>\n\n\n\n
    The game loop<\/h3>\n\n\n\n
    The game is a simple ultimatum game. The first proposer (Alice) puts a split on the table. The other player can accept<\/strong> (deal done), reject<\/strong> (both get $0) or counter<\/strong> (roles swap). Each agent’s move is parsed from free-form model output with a regex:<\/p>\n\n\n\n
    _ACTION_RE = re.compile(r\"(OFFER|ACCEPT|COUNTER|REJECT)\", re.IGNORECASE)\n\ndef parse_move(text):\n    match = _ACTION_RE.search(text)\n    if match is None: return None\n    action = match.group(1).upper()\n    if action in (\"ACCEPT\", \"REJECT\"):\n        return {\"action\": action}\n    numbers = _NUMBERS_RE.findall(text)\n    keep = int(numbers[0]) if numbers else None\n    return {\"action\": action, \"keep\": keep}\n<\/code><\/pre>\n\n\n\n
    Running the game<\/h3>\n\n\n\n
    python 02_agent_vs_agent\/game.py           # verbose: shows raw model text\npython 02_agent_vs_agent\/game.py --quiet   # only parsed moves\n<\/code><\/pre>\n\n\n\n
    Example session (2 turns, quiet mode):<\/p>\n\n\n\n
    Alice opens the negotiation...\nAlice -> Alice keeps $50, gives $50          # fair start\nBob   -> Bob keeps $70, gives $30            # aggressive counter\nAlice -> Alice keeps $40, gives $60          # concedes but no deal\n\nNo deal after 2 turns. Impasse.\n<\/code><\/pre>\n\n\n\n
    With --verbose<\/code> you see the raw model text, which is often more entertaining:<\/p>\n\n\n\n
    Bob says: \"OFFER 70 30. Take it or leave it, Alice.\n           I've got other deals lined up.\"\n<\/code><\/pre>\n\n\n\n
    What makes this example powerful is the lesson: multi-agent “collaboration” is not a framework feature<\/strong>. It is two single-agent loops passing messages through a shared state. The protocol (OFFER\/ACCEPT\/COUNTER\/REJECT) is just text matching. You can build any multi-agent system on the same pattern.<\/p>\n\n\n\n
    \n\n\n\n
    7. Putting It All Together<\/h2>\n\n\n\n
    Here is the complete checklist to build your own agent from scratch:<\/p>\n\n\n\n
      \n
    1. One API client<\/strong> \u2014 OpenAI, Anthropic, whatever. The loop does not care which SDK you use; only the wire format of tool calls differs.<\/li>\n\n\n\n
    2. A message list<\/strong> \u2014 system prompt, user messages, assistant replies, tool results. That list is<\/em> the agent’s memory.<\/li>\n\n\n\n
    3. A tool registry<\/strong> \u2014 a dict mapping names to Python functions. Each function is described by a JSON schema the model can read.<\/li>\n\n\n\n
    4. A while-loop<\/strong> \u2014 send the message list + tool schemas to the model. If the model requests a tool call, execute it, append the result, loop. If it returns text, stop and return it.<\/li>\n\n\n\n
    5. Multi-agent<\/strong> \u2014 run two copies of the same loop with different system prompts. Define a message protocol. Let them talk.<\/li>\n<\/ol>\n\n\n\n
      That is all of it. Frameworks add caching, streaming, retries, GUIs and marketing \u2014 but underneath every single one is this same loop. Once you have written it by hand, every framework becomes obvious (and often visibly over-engineered).<\/p>\n\n\n\n
      \n\n\n\n
      Going Further<\/h2>\n\n\n\n