Roadmap

Where we're going today

• 1 · Prepare — GitHub Student Pack, VS Code, Copilot · at home
• 2 · Vibe coding — solve a real PS1 question with AI · in class
• 3 · Agents — build AI that uses tools & loops · in class
• 4 · Workshop — a research-assistant agent · at home

Warm-up ispow2(n)

Give the AI the constraints, not just the goal

# no bin / len / logs / strings — bit ops only. 0 is NOT a power of two.
def ispow2(n):
    return n > 0 and (n & (n - 1)) == 0

Tell it the forbidden built-ins up front — or it reaches for bin().

Demo longest_run(n)

Watch the loop on a real question

longest_run(n) → length of the longest run of consecutive 1 bits.

• Turn 1 — ask (it uses forbidden bin() 👀)
• Turn 2 — visualize the bits
• Turn 3 — write tests → green
• Turn 4 — catch the rule break → refactor → still green
• Turn 5 — push on edge cases & complexity

Before your turn

How to talk to the AI

• 🎯 Be specific — exact behavior, not vibes
• 🚧 State constraints — what's forbidden & required
• 🔢 Give examples — input → output pairs
• 🪜 Small steps — solve → test → edge cases
• 🕵️ Read every line — confident ≠ correct

The core idea

A single answer vs. an agent that acts

What is a tool?

A normal typed function the model can call

@agent.tool_plain
def word_count(text: str) -> int:
    """Return the number of words in the given text."""
    return len(text.split())

The docstring is the tool's instruction manual for the model.

Your stack = 3 choices

Framework · Model · Harness

Model & framework are easy swaps. The harness is what makes an agent good.

Architectures · first cut

Workflow vs. agent

Same brick underneath: the augmented LLM (model + tools + memory).

Architectures · the ladder simple → complex

Six patterns you compose

• 1 · Single agent — one loop + tools · start here
• 2 · Prompt chain — sub-agents in a fixed flow, A → B → C
• 3 · Routing — classify, hand off to the right specialist
• 4 · Parallelization — fan-out / fan-in (split, or vote)
• 5 · Orchestrator + specialists — boss plans & delegates · the workhorse
• 6 · Evaluator–optimizer — generate ⇄ critique, loop

Scaling up · & the one rule

Topologies — and start simple

Rule: every layer adds cost, latency & failure points. Use the fewest pieces that solve it.

No credit card needed

Free tokens — and a cap so the loop can't run away

• 🟢 Gemini free tier — key from aistudio.google.com, generous requests/day
• 🔵 OpenRouter — one key, many models tagged :free
• 🚦 UsageLimits(request_limit=5) → raises UsageLimitExceeded

Because agents loop, always cap the number of requests.

▶ Live first_agent.py

One tool · free model · structured output · capped

class Answer(BaseModel):
    result: int

agent = Agent("google-gla:gemini-2.0-flash", output_type=Answer)

@agent.tool_plain
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

out = agent.run_sync("What is 21 + 21? Use the add tool.",
                     usage_limits=UsageLimits(request_limit=5))
print(out.output.result)   # -> 42

Assume it misbehaves

Failure modes → guardrails

• Runaway loop → UsageLimits
• Bad tool call → ModelRetry
• Hallucination → structured output + eval
• Prompt injection → treat tool output as untrusted
• Unsafe action → human-in-the-loop
• Silent regressions → tracing + evals