Build It: A Minimal AI Agent Loop From Scratch

No framework, just the loop

Every 'agent' library — LangChain, CrewAI, LangGraph — is built on the same 20-line core. Writing it by hand once makes every library make sense forever. We'll build an agent that can search the web, read files, and do math.

# pyproject.toml: anthropic, httpx
import json
import httpx
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-opus-4-7"

# --- Tools the agent can use ---

def tool_calculate(expression: str) -> str:
    # Pretend-safe eval for a DEMO — never use eval on untrusted input in production.
    allowed = set("0123456789+-*/(). ")
    if not set(expression).issubset(allowed):
        return "Error: expression has disallowed characters"
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"

def tool_fetch(url: str) -> str:
    try:
        r = httpx.get(url, timeout=10, headers={"User-Agent": "tendril-agent/1.0"})
        r.raise_for_status()
        return r.text[:4000]
    except Exception as e:
        return f"Error fetching: {e}"

TOOLS = {
    "calculate": tool_calculate,
    "fetch_url": tool_fetch,
}Two tools: a sandboxed calculator and a URL fetcher. Real tools would be broader.

TOOL_SPECS = [
    {
        "name": "calculate",
        "description": "Evaluate a basic arithmetic expression. Only digits, +,-,*,/,()",
        "input_schema": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
        },
    },
    {
        "name": "fetch_url",
        "description": "Fetch the first 4KB of text from a URL.",
        "input_schema": {
            "type": "object",
            "properties": {"url": {"type": "string"}},
            "required": ["url"],
        },
    },
]Tool specs — what the model sees when deciding which tool to call.

def run_agent(task: str, max_steps: int = 8) -> str:
    messages = [{"role": "user", "content": task}]

    for step in range(max_steps):
        response = client.messages.create(
            model=MODEL,
            max_tokens=1500,
            tools=TOOL_SPECS,
            messages=messages,
        )

        # Save assistant turn
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            # Agent is done — return final text
            for block in response.content:
                if block.type == "text":
                    return block.text
            return "(no text)"

        # Otherwise gather tool calls and run them
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                func = TOOLS.get(block.name)
                result = func(**block.input) if func else f"No such tool: {block.name}"
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(result),
                })
        messages.append({"role": "user", "content": tool_results})

    return "Agent exceeded max steps without finishing."

if __name__ == "__main__":
    print(run_agent("What is 25 * 34, and what's on https://example.com — give one sentence about each."))The loop: call model → if tools, run them and feed back → if done, return. That's the entire agent.

Advanced: persistent memory

# Save the messages list to disk so the agent can resume a conversation
import json
from pathlib import Path

def save_state(messages, path=Path("agent_state.json")):
    # Serialize tool_use/tool_result blocks into dicts
    serialized = []
    for m in messages:
        if isinstance(m["content"], str):
            serialized.append(m)
        else:
            serialized.append({
                "role": m["role"],
                "content": [b.model_dump() if hasattr(b, "model_dump") else b for b in m["content"]]
            })
    path.write_text(json.dumps(serialized, indent=2))Turning agent state into JSON lets you pause and resume — the foundation of every production agent.

Mini-exercise

1. Add a tool read_file(path: str) that returns the first 2KB of a local file
2. Add a max-cost guard: estimate tokens per step and stop if over budget
3. Ask the agent to 'read my notes.txt and summarize'
4. Print the step-by-step trace so you can see what tools it chose

Big idea: an agent is shockingly simple code. Frameworks add conveniences (retries, logging, streaming), but the core is a for-loop with two cases: 'call a tool' or 'stop.'