M00B: Hello World — Three Ways to Build an Agent

Before you spend 30 modules on agent theory, build the same tiny agent three different ways — raw API, Agent SDK, and spec-driven — in one sitting. By the end, you'll know which approach each later module is teaching you, and why.

Learning Objectives

• Build the same "time helper" agent three different ways: raw Messages APIAnthropic's HTTP endpoint for sending a list of messages to Claude and getting back a response. The lowest-level building block in this course., claude-agent-sdk, and a spec-driven generation
• Recognise the hand-rolled tool-use loopA while-loop that sends messages to Claude, checks if Claude requested a tool, runs that tool, sends the result back, and repeats until the model says it's done. — and see exactly what the SDK abstracts away
• Read a real agent-spec.md and watch Claude Code generate the entire agent from it
• Identify which approach matches your situation: learning, shipping, or prototyping fast
• Map the three tiers (Tier 1, Tier 2, Tier 3) to the modules and capstones you'll meet later in the course

Why Three Approaches?

The Abstraction Ladder

Each approach hides more of the machinery. The animation below climbs the ladder one rung at a time. Watch the red boxes (the parts you have to write) shrink, and the cyan/pink boxes (the parts the SDK or generator handles) grow.

Setup (5 minutes)

You'll build all three versions in a single project folder. Each version is self-contained so you can run them independently.

STEP 1Create the project and a virtual environment.

mkdir hello-agent && cd hello-agent
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows PowerShell:
# .venv\Scripts\Activate.ps1

STEP 2Install dependencies for all three approaches. The raw approach needs only anthropic. The SDK and spec-driven approaches need claude-agent-sdk. Claude Code is the CLI that powers the spec-driven generation.

# Python packages
pip install anthropic claude-agent-sdk

# Claude Code CLI (for Approach 3)
npm install -g @anthropic-ai/claude-code

# Node.js packages (only if you want the JS versions)
npm init -y
npm install @anthropic-ai/sdk @anthropic-ai/claude-agent-sdk

STEP 3Set your API key. Get one from console.anthropic.com. Both the raw API and the SDK read this environment variable.

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Approach 1 — Raw Messages API

What you're building: An agent that answers "what time is it in [city]?" by calling a get_time tool. The agent has zero scaffolding — you write the entire loop. Everything you'll learn in M01–M11 lives inside this file.

The Code

Save this as raw_agent.py. Read the comments — they label every step of the loop above.

"""raw_agent.py — Hello World, hand-rolled tool-use loop."""
import os
from datetime import datetime
from zoneinfo import ZoneInfo
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

# ---- Tool implementation (plain Python) ----
TIMEZONES = {
    "new york": "America/New_York",
    "london": "Europe/London",
    "tokyo": "Asia/Tokyo",
    "sydney": "Australia/Sydney",
    "san francisco": "America/Los_Angeles",
}

def get_time(city: str) -> str:
    tz_name = TIMEZONES.get(city.lower())
    if tz_name is None:
        return f"Unknown city: {city}. Known cities: {', '.join(TIMEZONES)}."
    now = datetime.now(ZoneInfo(tz_name))
    return now.strftime("%H:%M on %A, %d %b %Y")

# ---- Tool schema (what Claude sees) ----
TOOLS = [{
    "name": "get_time",
    "description": "Get the current local time in a major city.",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. Tokyo"}
        },
        "required": ["city"],
    },
}]

# ---- The loop ----
def run_agent(user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]
    while True:
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=TOOLS,
            messages=messages,
        )

        # Step 2: did Claude finish?
        if resp.stop_reason == "end_turn":
            return "".join(b.text for b in resp.content if b.type == "text")

        # Step 3+4: Claude requested at least one tool call.
        messages.append({"role": "assistant", "content": resp.content})
        tool_results = []
        for block in resp.content:
            if block.type != "tool_use":
                continue
            if block.name == "get_time":
                result_text = get_time(block.input["city"])
            else:
                result_text = f"Unknown tool: {block.name}"
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result_text,
            })
        messages.append({"role": "user", "content": tool_results})
        # Step 5: loop back

if __name__ == "__main__":
    print(run_agent("What time is it in Tokyo right now?"))

// raw_agent.mjs — Hello World, hand-rolled tool-use loop.
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

const TIMEZONES = {
  "new york": "America/New_York",
  "london": "Europe/London",
  "tokyo": "Asia/Tokyo",
  "sydney": "Australia/Sydney",
  "san francisco": "America/Los_Angeles",
};

function getTime(city) {
  const tz = TIMEZONES[city.toLowerCase()];
  if (!tz) return `Unknown city: ${city}. Known cities: ${Object.keys(TIMEZONES).join(", ")}.`;
  return new Intl.DateTimeFormat("en-GB", {
    timeZone: tz, hour: "2-digit", minute: "2-digit",
    weekday: "long", day: "2-digit", month: "short", year: "numeric",
  }).format(new Date());
}

const TOOLS = [{
  name: "get_time",
  description: "Get the current local time in a major city.",
  input_schema: {
    type: "object",
    properties: { city: { type: "string", description: "City name, e.g. Tokyo" } },
    required: ["city"],
  },
}];

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];
  while (true) {
    const resp = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      tools: TOOLS,
      messages,
    });

    if (resp.stop_reason === "end_turn") {
      return resp.content.filter(b => b.type === "text").map(b => b.text).join("");
    }

    messages.push({ role: "assistant", content: resp.content });
    const toolResults = [];
    for (const block of resp.content) {
      if (block.type !== "tool_use") continue;
      const text = block.name === "get_time"
        ? getTime(block.input.city)
        : `Unknown tool: ${block.name}`;
      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: text });
    }
    messages.push({ role: "user", content: toolResults });
  }
}

console.log(await runAgent("What time is it in Tokyo right now?"));

Run It

# Python
python raw_agent.py

# Node.js
node raw_agent.mjs

The current local time in Tokyo is 14:37 on Friday, 09 May 2026.

Approach 2 — claude-agent-sdk

Same agent, fewer lines. The SDK hides the loop, the message accumulation, and the JSON tool schemas. You declare tools as decorated functions, declare options once, then call query() and consume an async stream.

The Code

Save this as sdk_agent.py. Note the call to the model is now a single async for — everything else is configuration.

"""sdk_agent.py — Hello World, claude-agent-sdk."""
import asyncio
from datetime import datetime
from zoneinfo import ZoneInfo

from claude_agent_sdk import (
    query,
    tool,
    create_sdk_mcp_server,
    ClaudeAgentOptions,
    AssistantMessage,
)

TIMEZONES = {
    "new york": "America/New_York",
    "london": "Europe/London",
    "tokyo": "Asia/Tokyo",
    "sydney": "Australia/Sydney",
    "san francisco": "America/Los_Angeles",
}

@tool("get_time", "Get the current local time in a major city.", {"city": str})
async def get_time(args):
    tz_name = TIMEZONES.get(args["city"].lower())
    if tz_name is None:
        text = f"Unknown city: {args['city']}. Known cities: {', '.join(TIMEZONES)}."
    else:
        text = datetime.now(ZoneInfo(tz_name)).strftime("%H:%M on %A, %d %b %Y")
    return {"content": [{"type": "text", "text": text}]}

server = create_sdk_mcp_server(name="time_tools", version="1.0.0", tools=[get_time])

options = ClaudeAgentOptions(
    system_prompt="You are a friendly time assistant. Always include the day of the week.",
    mcp_servers={"time": server},
    allowed_tools=["mcp__time__get_time"],
    max_turns=4,
    model="claude-sonnet-4-6",
)

async def main():
    async for msg in query(prompt="What time is it in Tokyo right now?", options=options):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if hasattr(block, "text"):
                    print(block.text)

if __name__ == "__main__":
    asyncio.run(main())

// sdk_agent.mjs — Hello World, claude-agent-sdk.
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const TIMEZONES = {
  "new york": "America/New_York",
  "london": "Europe/London",
  "tokyo": "Asia/Tokyo",
  "sydney": "Australia/Sydney",
  "san francisco": "America/Los_Angeles",
};

const getTimeTool = tool(
  "get_time",
  "Get the current local time in a major city.",
  { city: z.string() },
  async (args) => {
    const tz = TIMEZONES[args.city.toLowerCase()];
    const text = !tz
      ? `Unknown city: ${args.city}. Known cities: ${Object.keys(TIMEZONES).join(", ")}.`
      : new Intl.DateTimeFormat("en-GB", {
          timeZone: tz, hour: "2-digit", minute: "2-digit",
          weekday: "long", day: "2-digit", month: "short", year: "numeric",
        }).format(new Date());
    return { content: [{ type: "text", text }] };
  }
);

const server = createSdkMcpServer({ name: "time_tools", tools: [getTimeTool] });

for await (const msg of query({
  prompt: "What time is it in Tokyo right now?",
  options: {
    systemPrompt: "You are a friendly time assistant. Always include the day of the week.",
    mcpServers: { time: server },
    allowedTools: ["mcp__time__get_time"],
    maxTurns: 4,
    model: "claude-sonnet-4-6",
  },
})) {
  if (msg.type === "assistant") {
    for (const block of msg.content) {
      if (block.text) console.log(block.text);
    }
  }
}

Run It

# Python
python sdk_agent.py

# Node.js (needs "type": "module" in package.json)
node sdk_agent.mjs

The current local time in Tokyo is 14:37 on Friday, 09 May 2026.

Approach 3 — Spec-Driven

This is the approach you'll use on every Tier 3 capstone (M15B and CAPSTONEs 1–5/7). Instead of writing the agent, you write a specification — a markdown file that describes what the agent does, what tools it has, and what tests should pass. Then you ask Claude CodeAnthropic's terminal-based AI engineer. The CLI you installed in Step 2. It can read your project, generate files, run commands, and iterate based on feedback. to build the project.

The Spec

Create the folder and save the file below as spec/agent-spec.md. This is a real, complete spec — not pseudocode. Read it carefully; every section has a purpose.

mkdir -p spec
# then save the file below as spec/agent-spec.md

# Agent Specification: Time Helper

## Overview
A small assistant agent that answers natural-language questions about the
current local time in major world cities. Built as the canonical "Hello World"
example for spec-driven agent development.

## Agent Configuration
- Model: claude-sonnet-4-6
- Framework: claude-agent-sdk (Python). Use `query`, `tool`,
  `create_sdk_mcp_server`, `ClaudeAgentOptions`, and `AssistantMessage`.
- Max turns per request: 4
- Max tokens per response: 1024
- Temperature: default

## System Prompt
You are a friendly time assistant. When asked about the time, always call the
get_time tool rather than guessing. Always include the day of the week and the
city in your response. If the user asks for an unknown city, apologise briefly
and list the cities you know about.

## Tools

### get_time
- Description: Get the current local time in a major city.
- Parameters: city (string, required) — name of a city such as "Tokyo".
- Returns: A short string of the form "HH:MM on Weekday, DD Mon YYYY".
- Implementation: Use Python's `zoneinfo.ZoneInfo` with this exact mapping:
  - "new york"      -> "America/New_York"
  - "london"        -> "Europe/London"
  - "tokyo"         -> "Asia/Tokyo"
  - "sydney"        -> "Australia/Sydney"
  - "san francisco" -> "America/Los_Angeles"
  Lookup must be case-insensitive. Unknown cities return:
  "Unknown city: {city}. Known cities: {comma-separated list}."

## Files to Generate
- `agent.py`             — entry point. Wires the tool, options, and async loop.
- `tests/test_agent.py`  — pytest tests (see "Tests" below).
- `requirements.txt`     — pinned `claude-agent-sdk` and `pytest`.
- `README.md`            — one paragraph: what it does and how to run it.

## Tests (must all pass)
1. `get_time` for "Tokyo" returns a string matching the regex
   `^\d{2}:\d{2} on \w+, \d{2} \w{3} \d{4}$`.
2. `get_time` for "Mars" returns a string starting with "Unknown city:".
3. Lookup is case-insensitive: "TOKYO", "tokyo", and "ToKyO" all succeed.

## Out of Scope
- Persistence / sessions
- Hooks or permission gates (those come in M16/M17/M26)
- Multi-language responses

Generate & Run

From the project root, with the spec saved, run Claude Code with this exact prompt:

claude "Read spec/agent-spec.md and build the entire project as described. \
Generate every file in 'Files to Generate', then run pytest and show me the results."

Claude Code will read the spec, generate agent.py, the tests, the requirements file, and the README, then execute the test suite. Watch it work — the workflow is the lesson.

Created agent.py
Created tests/test_agent.py
Created requirements.txt
Created README.md
Running: pytest -q
...                                                                      [100%]
3 passed in 0.42s

Now run the generated agent end-to-end:

python agent.py

Side-by-Side

The same agent, three abstractions. Numbers below come from the actual files you just wrote.

When to Use Which

Knowledge Check

Five quick questions to lock in the difference between the three approaches before you move on to M01.

Module Summary