Lesson 5 - Guided Project: Design the Atlas Agent

Welcome to the Guided Project#

You’ve spent this module learning what an agent is, when to reach for one, what it’s made of, and how a system prompt shapes it. Now you’ll put all of that to work — not by writing code, but by designing. In this guided project, you’ll design Atlas, a trip-planning research agent that you’ll go on to build, piece by piece, across the rest of the course. By the end, Atlas will help a user plan a short trip: pick a destination, check the practical details, and draft an itinerary. Today, before a single line of implementation, you’ll decide exactly what Atlas is, what it can do, and how it will think.

This is the most important habit in agent building: sketch the interface before you write the implementation. A clear design tells you what to build and stops you from building the wrong thing. So put the editor aside for now — this lesson lives on paper (or in comments), and the only “code” you’ll write is a sketch of tool signatures, which are themselves a design artifact.

By the end of this project, you will be able to:

• Define an agent’s goal and write its instructions (system prompt)
• Justify whether a task is a good fit for an agent using the Lesson 2 checklist
• Sketch an agent’s tools as clear interfaces (name, purpose, inputs)
• Map a project onto the anatomy parts — model, instructions, tools, loop, memory, stopping conditions — and trace its loop in plain language

Let’s design Atlas, one stage at a time.

Stage 1: Define the Goal#

Every agent starts with a goal — a plain statement of what you want accomplished. Atlas’s goal is small and concrete on purpose:

Atlas helps a user plan a short trip. It helps them pick a destination that fits their interests and season, checks the practical details (weather, rough costs, currency), and drafts a day-by-day itinerary they can actually use.

Notice what the goal is not. It’s not “be a travel expert” or “answer any travel question.” A sharp, bounded goal makes every later decision easier: it tells you which tools Atlas needs, what a finished result looks like, and when the agent is done.

With the goal fixed, write the instructions — the system prompt that tells Atlas how to behave while pursuing that goal. A good first draft for Atlas:

You are Atlas, a friendly and practical trip-planning assistant. Your job is to help the user plan a short trip: choosing a destination, checking practical details, and drafting an itinerary. Ask clarifying questions when the request is vague — for example, about budget, travel season, trip length, and the kinds of things the user enjoys. When you make a suggestion, briefly explain why it fits what the user told you. Use your tools to look up real information (destinations, weather, currency) rather than guessing. Keep your tone warm and your suggestions concrete.

That prompt does the three jobs a good system prompt should: it gives Atlas a role (a practical trip planner), describes how to behave (ask clarifying questions, explain its reasoning), and sets boundaries (use tools instead of guessing, stay focused on planning a short trip).

Stage 2: Is It Even an Agent?#

Before committing to an agent, run the task through the checklist from Lesson 2. An agent is the right tool when the task is genuinely multi-step and the path can’t be hardcoded in advance. Let’s check trip planning against the four questions:

• Complexity. Is the task multi-step, with a path that depends on what’s discovered along the way? Yes. The user might say “somewhere relaxed in autumn, on a budget.” Atlas has to figure out candidate destinations, then check the weather for those specific places, then check costs, then assemble an itinerary. Each step depends on the answers to the last — you can’t write a fixed script for it, because the second step isn’t knowable until the first finishes.
• Value. Is the outcome worth the extra cost and latency of a loop? For a trip the user actually cares about, yes — a thoughtful, personalized itinerary is worth more than a single canned paragraph.
• Viability. Is this the kind of task a language model is good at? Yes. Trip planning is reasoning over preferences, combining looked-up facts, and writing clear suggestions — squarely in a model’s wheelhouse.
• Cost of error. If Atlas suggests a so-so restaurant or a slightly-off itinerary, can the user catch and recover from it easily? Yes — the user reviews the plan before acting on it, and mistakes are low-stakes and easy to correct.

Trip planning passes on all four counts, and the deciding factor is the first one: the path depends on the answers. A request like “plan a relaxed 3-day autumn trip somewhere in Japan, budget-friendly” can’t be served by one fixed sequence of steps — Atlas has to decide what to look up next based on what it’s learned. That’s exactly the situation an agent is built for.

(If the task were instead “convert these prices to euros,” that’s a single tool call with a fixed path — a plain function or workflow, not an agent. The contrast is worth keeping in mind: don’t reach for an agent when the steps never change.)

Stage 3: List the Tools#

Tools are the actions Atlas can request — they’re what let it go get information instead of guessing. At the design stage, you don’t implement tools; you specify their interface: a name, a one-line description of what it does, and its inputs. (The model never runs these itself — it requests them, and your code performs them. You’ll write the real implementations in later modules.)

Here are the tools Atlas needs, derived directly from its goal:

• search_destinations(interest, season) — Suggest candidate destinations that fit a given interest (e.g. “relaxed,” “food,” “hiking”) and travel season.
• get_weather(city) — Look up typical or current weather conditions for a city, so the itinerary matches the season.
• convert_currency(amount, from_currency, to_currency) — Convert an amount between currencies, to help the user reason about costs in their own money.
• build_itinerary(city, days) — Assemble a day-by-day plan for a city across a number of days.

Because these are design artifacts, it’s natural to write them as Python function stubs — the signatures and docstrings, with empty bodies. This is still design, not implementation: there’s no logic here, just the contract each tool will fulfill. We’ll fill these in later in the course.

# Atlas tool interfaces (design sketch only).
# These are the contracts, not the implementations — we'll build the
# real bodies in later modules. For now we're just deciding the shape
# of each action Atlas can request.

def search_destinations(interest: str, season: str) -> list[str]:
    """Suggest candidate destinations matching an interest and season.

    Args:
        interest: What the traveler enjoys, e.g. "relaxed", "food", "hiking".
        season: The travel season, e.g. "autumn", "summer".

    Returns:
        A list of suggested destination names.
    """
    ...


def get_weather(city: str) -> str:
    """Look up typical weather for a city so plans suit the season.

    Args:
        city: The city to check, e.g. "Kyoto".

    Returns:
        A short description of the weather conditions.
    """
    ...


def convert_currency(amount: float, from_currency: str, to_currency: str) -> float:
    """Convert an amount from one currency to another.

    Args:
        amount: The amount to convert.
        from_currency: Source currency code, e.g. "USD".
        to_currency: Target currency code, e.g. "JPY".

    Returns:
        The converted amount.
    """
    ...


def build_itinerary(city: str, days: int) -> str:
    """Assemble a day-by-day itinerary for a city.

    Args:
        city: The destination city.
        days: How many days the trip lasts.

    Returns:
        A formatted day-by-day plan.
    """
    ...

A good tool interface is small, clearly named, and obvious about its inputs — so that both you and the model can tell at a glance when to use it. We’ll come back to the craft of tool design in depth later; for now, the goal is just a clear sketch.

Stage 4: Map the Anatomy#

In Lesson 3 you learned the parts every agent is assembled from. Designing Atlas is largely a matter of filling each part in. Here’s the whole agent on one page:

• Model — claude-haiku-4-5. It’s the “brain” that does the deciding. Haiku is fast and economical, which makes it a sensible choice for an interactive, multi-turn assistant like Atlas where the per-step reasoning is moderate rather than extreme.
• Instructions — the system prompt from Stage 1: a friendly, practical trip planner that asks clarifying questions, explains its suggestions, and uses tools instead of guessing.
• Tools — the four interfaces from Stage 3: search_destinations, get_weather, convert_currency, and build_itinerary.
• The loop — the decide-act-observe cycle. Atlas decides whether it can answer or needs a tool, your code runs any tool it requests, the result is fed back, and it decides again. You’ll build this loop for real in Module 2.
• Memory — the conversation so far. Atlas needs to remember what the user already told it (budget, season, interests, the destination it settled on) so each new step builds on the last rather than starting over.
• Stopping conditions — the natural stop is a finished itinerary: when Atlas has a day-by-day plan that matches the user’s request, it returns it and ends the loop. As a safety guardrail, you also set a maximum number of steps (or turns) so a confused agent fails safely instead of looping forever.

That’s a complete agent design. Every part has a concrete answer, and each answer traces back to the goal you set in Stage 1.

Stage 5: Sketch the Loop in Plain Language#

The real test of a design is whether you can trace the loop it would run. Let’s walk Atlas through a sample request, in plain language, the way it would actually unfold:

User: “Plan me a relaxed 3-day autumn trip somewhere in Japan, budget-friendly.”

1. Decide. Atlas reads the request. It has an interest (“relaxed”), a season (“autumn”), a length (3 days), and a region (Japan), but no specific destination yet. It decides it needs candidate destinations, so it requests search_destinations("relaxed", "autumn").
2. Act → Observe. Your code runs the tool and feeds the result back: a few relaxed-friendly Japanese destinations, say Kyoto, Kanazawa, Hakone.
3. Decide. Now Atlas has candidates but wants to make sure the weather suits an autumn trip. It picks Kyoto as a strong fit and requests get_weather("Kyoto").
4. Act → Observe. The result comes back: mild, clear autumn days — good for walking. That confirms Kyoto is a sensible choice.
5. Decide. The user said “budget-friendly,” so Atlas wants to help them reason about cost in their own currency. It requests convert_currency(50000, "JPY", "USD") to give a sense of a daily budget in familiar terms.
6. Act → Observe. The converted amount comes back, and Atlas now has everything it needs: a destination, confirmation it fits the season, and a cost reference point.
7. Decide. Time to assemble the plan. Atlas requests build_itinerary("Kyoto", 3).
8. Act → Observe. A day-by-day Kyoto itinerary comes back.
9. Decide → Finish. Atlas judges that it has a finished itinerary that matches the request — relaxed, 3 days, autumn-appropriate, budget-conscious. The stopping condition is met, so instead of calling another tool, it returns the final plan to the user, explaining briefly why Kyoto and why this itinerary.

Read back over those steps and notice the defining feature again: each tool call was chosen based on the result of the previous one. Atlas didn’t follow a script — it decided what to look up next as it learned more. That’s the agent loop, and it’s exactly what you designed Atlas to do.

Extend the Design#

You’ve designed Atlas end to end. Now stretch the design a little — these exercises are best done on paper, the same way the lesson was.

Exercise 1: Add a tool Atlas is missing#

Atlas can suggest destinations, check weather, convert currency, and build an itinerary — but a real trip planner needs at least one more capability. Name a tool Atlas is missing, write its one-line description and its inputs, and say which loop step would call it.

Exercise 2: Write a stricter system prompt#

The Stage 1 prompt is friendly and open. Rewrite it to be stricter — for instance, requiring Atlas to always confirm budget and trip length before suggesting any destination, and to refuse to draft an itinerary until both are known.

Exercise 3: Choose a sensible max-step limit#

Atlas’s natural stop is a finished itinerary, but it also needs a safety limit. Decide a maximum number of steps (or turns) for Atlas and justify it: too low and Atlas can’t finish a normal request; too high and a confused agent wastes time and money before failing.

Summary#

In this guided project you designed Atlas, the trip-planning agent you’ll build across the course — entirely on paper, before writing any implementation. You defined its goal (help a user plan a short trip) and wrote its instructions (a friendly, practical planner that asks clarifying questions and explains its suggestions). You ran trip planning through the agent-vs-workflow checklist and justified it as a genuine agent use case, because the path depends on the answers. You sketched Atlas’s tools as clean interfaces, mapped the project onto every part of the anatomy — model, instructions, tools, loop, memory, stopping conditions — and traced the decide-act-observe loop for a real request, watching each tool call get chosen from the result of the last. That design is now your blueprint for the rest of the course.

Key Concepts#

• Goal and instructions — a sharp, bounded goal plus a system prompt that sets role, behavior, and boundaries.
• Agent-vs-workflow check — trip planning qualifies because it’s multi-step and the path depends on what’s discovered.
• Tool interfaces — name, one-line description, and inputs; the contract, designed before the implementation.
• Anatomy mapping — model (claude-haiku-4-5), instructions, tools, loop, memory (the conversation), stopping conditions (finished itinerary, or a max-step limit).
• Loop trace — decide → act → observe → repeat, with each step chosen from the previous result.

Why This Matters#

Real agent projects don’t begin in an editor — they begin with a design like this one. Deciding what an agent is for, what it can do, and when it’s done before writing code is the difference between a focused build and an aimless one. The discipline of sketching the interface first — exactly what you just practiced with Atlas — is how professionals avoid building the wrong thing. And because you now have a concrete blueprint, the rest of the course has somewhere to go: each module adds a real, working piece to the Atlas you designed here, starting with the loop itself.

Next Steps#

Continue Building Your Skills#

You’ve finished Module 1 — and you’ve got more than a set of concepts to show for it. You have Atlas: a real agent, designed end to end, waiting to be built. You know its goal, its instructions, its tools, its anatomy, and the loop it will run. Next, in Module 2, you’ll bring that loop to life in real Python with Claude’s tool use — turning the design you just drew into an agent that actually decides, acts, and observes.