Build your first agent in 100 lines.

{"type": "tool_use", "id": "toolu_3", "name": "read_file", "input": {"path": "notes/launch.md"}}

{"type": "tool_result", "tool_use_id": "toolu_3", "content": "# Launch plan\n\nLaunch date: October 14\nOwner: Sam\n", "is_error": false}

mkdir first-agent && cd first-agent
python3 -m venv .venv && source .venv/bin/activate
pip install anthropic
mkdir -p workspace/notes
printf '# Launch plan\n\nLaunch date: October 14\nOwner: Sam\n' > workspace/notes/launch.md
printf '# To do\n\n- Book the venue\n' > workspace/notes/todo.md

import sys
from pathlib import Path

import anthropic

MODEL = "claude-opus-5-5"
MAX_STEPS = 10  # guardrail: never loop forever
WORKSPACE = Path("workspace").resolve()  # guardrail: the only folder the agent can touch

TOOLS = [
    {
        "name": "list_files",
        "description": "List every file in the workspace. Call this first to see what exists.",
        "input_schema": {"type": "object", "properties": {}},
    },
    {
        "name": "read_file",
        "description": "Read a text file from the workspace. Call this when you need its contents.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string", "description": "Path inside the workspace"}},
            "required": ["path"],
        },
    },
    {
        "name": "append_line",
        "description": "Add one line to the end of a workspace file. The user must approve it.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path inside the workspace"},
                "line": {"type": "string", "description": "The line to add"},
            },
            "required": ["path", "line"],
        },
    },
]


def safe_path(relative: str) -> Path:
    path = (WORKSPACE / relative).resolve()
    if not path.is_relative_to(WORKSPACE):
        raise ValueError(f"{relative} is outside the workspace")
    return path


def run_tool(name: str, args: dict) -> str:
    if name == "list_files":
        files = sorted(p for p in WORKSPACE.rglob("*") if p.is_file())
        return "\n".join(str(p.relative_to(WORKSPACE)) for p in files)
    if name == "read_file":
        return safe_path(args["path"]).read_text()[:10_000]
    if name == "append_line":
        path = safe_path(args["path"])
        answer = input(f"Allow: add {args['line']!r} to {args['path']}? [y/N] ")
        if answer.strip().lower() != "y":
            return "The user declined."
        with path.open("a") as f:
            f.write(args["line"] + "\n")
        return "Line added."
    raise ValueError(f"Unknown tool: {name}")


def run_agent(client, task: str) -> None:
    messages = [{"role": "user", "content": task}]
    for step in range(1, MAX_STEPS + 1):
        response = client.messages.create(
            model=MODEL, max_tokens=16000, tools=TOOLS, messages=messages
        )
        messages.append({"role": "assistant", "content": response.content})
        for block in response.content:
            if block.type == "text" and block.text:
                print(f"[model] {block.text}")

        if response.stop_reason != "tool_use":  # end_turn, max_tokens, refusal...
            print(f"[stop] {response.stop_reason} after {step} steps")
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                print(f"[tool] {block.name} {block.input}")
                try:
                    output, failed = run_tool(block.name, block.input), False
                except Exception as err:
                    output, failed = f"Error: {err}", True
                    print(f"[error] {err}")
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": output, "is_error": failed})
        messages.append({"role": "user", "content": results})

    print(f"[stop] hit the {MAX_STEPS}-step limit")


if __name__ == "__main__":
    if "--fake" in sys.argv:
        from fake_model import FakeClient
        client = FakeClient()
    else:
        client = anthropic.Anthropic()  # the one line that needs your API key
    run_agent(client, "When is the launch? Add the date to notes/todo.md.")

"""A scripted stand-in for Claude, so agent.py runs without an API key.

It returns the SDK's own Message objects, so agent.py cannot tell the
difference, and it reacts to the tool results the loop sends back.
"""
import re

from anthropic.types import Message, TextBlock, ToolUseBlock, Usage


def reply(*blocks, stop_reason):
    return Message(id="msg_fake", type="message", role="assistant", model="fake",
                   content=list(blocks), stop_reason=stop_reason,
                   usage=Usage(input_tokens=0, output_tokens=0))


def call(n, name, **args):
    return ToolUseBlock(type="tool_use", id=f"toolu_{n}", name=name, input=args)


class FakeMessages:
    def create(self, *, messages, **request):
        results = [block for m in messages if m["role"] == "user"
                   and isinstance(m["content"], list) for block in m["content"]]
        for n, result in enumerate(results, start=1):  # each result must answer its call
            assert result["tool_use_id"] == f"toolu_{n}", "tool_result does not match"

        step = len(results)
        if step == 0:
            return reply(TextBlock(type="text", text="I'll check which files exist."),
                         call(1, "list_files"), stop_reason="tool_use")
        if step == 1:  # misbehave on purpose, to show the sandbox at work
            return reply(call(2, "read_file", path="../secrets.txt"), stop_reason="tool_use")
        if step == 2:
            launch = next(p for p in results[0]["content"].splitlines() if "launch" in p)
            return reply(call(3, "read_file", path=launch), stop_reason="tool_use")
        date = re.search(r"Launch date: (.+)", results[2]["content"]).group(1)
        if step == 3:
            return reply(call(4, "append_line", path="notes/todo.md", line=f"- Launch: {date}"),
                         stop_reason="tool_use")
        done = results[3]["content"] == "Line added."
        text = f"The launch is on {date}. " + ("I added it to notes/todo.md." if done
                                                 else "You declined, so I changed nothing.")
        return reply(TextBlock(type="text", text=text), stop_reason="end_turn")


class FakeClient:
    def __init__(self):
        self.messages = FakeMessages()

[model] I'll check which files exist.
[tool] list_files {}
[tool] read_file {'path': '../secrets.txt'}
[error] ../secrets.txt is outside the workspace
[tool] read_file {'path': 'notes/launch.md'}
[tool] append_line {'path': 'notes/todo.md', 'line': '- Launch: October 14'}
Allow: add '- Launch: October 14' to notes/todo.md? [y/N] y
[model] The launch is on October 14. I added it to notes/todo.md.
[stop] end_turn after 5 steps