Claude Architect · Lesson

When to Use an Agent

Agents vs simple prompts vs fixed pipelines.

When to Use an Agent is a free Claude Architect lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Three Ways to Solve a Task

Before you build anything with Claude, you make one key decision: how much autonomy does the task need? There are three patterns:

Simple prompt — one request, one reply.
Fixed pipeline — a known sequence of steps you wire up yourself.
Agent — the model decides which tools to call and when, looping until the work is done.

Picking the right one is an architecture decision. Over-build and you add cost and failure points; under-build and the task can't complete. This lesson teaches you to choose well.

The Simple Prompt

A simple prompt is a single API call: you send a system message plus messages, and you get one answer back. No tools, no loop.

Use it when the task is self-contained: rewriting text, summarizing a paragraph, classifying a sentence, answering a question from given context. If everything the model needs is already in the prompt, you don't need anything more.

Remember: the model keeps no state. Each call is independent — you must resend the full messages history yourself if you want continuity.

import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    system="You rewrite text to be clear and concise.",
    messages=[
        {"role": "user", "content": "Rewrite: 'The meeting, which was long, ended.'"}
    ],
)
print(resp.content[0].text)

The Fixed Pipeline

A fixed pipeline chains several steps in a known order. You — the architect — decide the sequence in code. Step 1 feeds step 2, which feeds step 3.

This is also called prompt chaining. Use it when the steps are known and sequential: extract fields, then validate them, then format a report. The model never chooses the path — you did, in advance.

Pipelines are predictable and easy to debug because the control flow is fixed. The trade-off is rigidity: they can't adapt when a task needs different steps depending on what they find.

# Fixed pipeline: each step's output feeds the next
extracted = extract_fields(document)        # step 1
validated = validate(extracted)             # step 2
report    = format_report(validated)        # step 3
# The sequence is hard-coded. The model never picks the path.

The Agent

An agent hands control flow to the model. You give Claude a goal and a set of tools, and the model decides which tool to call, inspects the result, and decides what to do next — looping until the goal is met.

The defining feature: decisions are model-driven, not hard-coded. You don't know in advance how many steps it will take or which tools it will use.

Use an agent when the path is open-ended: investigating a bug, researching a topic across sources, resolving a customer issue that might need a lookup, a refund, or an escalation depending on what's found.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="You are a support agent. Resolve the customer's issue.",
    tools=[get_customer, lookup_order, process_refund, escalate_to_human],
    messages=conversation,
)
# The model chooses which tool(s) to call based on the situation.

The Agentic Loop

An agent runs a loop driven by the response's stop_reason:

Send the request.
Inspect stop_reason.
If it is tool_use, run the requested tool(s), append the results to the message history, and send again.
Repeat until stop_reason is end_turn.

You terminate on the stop reason — the API's own signal that the turn is complete. This is the heart of every agent.

while True:
    resp = client.messages.create(model=MODEL, max_tokens=1024,
                                  system=SYSTEM, tools=TOOLS,
                                  messages=messages)
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason == "end_turn":
        break                       # task complete
    if resp.stop_reason == "tool_use":
        results = run_tools(resp.content)
        messages.append({"role": "user", "content": results})

Never Parse Text for 'Done'

A common and dangerous mistake: ending the loop by scanning the model's reply for words like "done" or "finished". The model might say "done" mid-thought, or never say it at all. This is a classic anti-pattern.

Always terminate on the stop_reason — end_turn means complete. The stop reason is a structured, reliable signal; free text is not.

Iteration caps (a maximum loop count) are a safety net to prevent runaway loops — never the primary stop mechanism. The real stop is always the stop reason.

# ANTI-PATTERN: do not do this
if "done" in resp.content[0].text.lower():
    break

# CORRECT: rely on the structured stop reason
if resp.stop_reason == "end_turn":
    break

Decision Rule: Is the Path Known?

Here is the single question that decides agent vs pipeline:

Do you know the steps in advance?

Yes, fixed and sequential → use a fixed pipeline (prompt chaining). It is cheaper, faster, and easier to debug.
No, open-ended investigation → use an agent with adaptive decomposition.

If a task needs no external data or actions at all and fits in one call, you don't even need a pipeline — a simple prompt is enough. Always reach for the simplest pattern that does the job.

Decisions vs Guarantees

Agents are powerful because the model decides — but model decisions are probabilistic (roughly 90% reliable), not certain. So a second rule applies:

Let the model decide; reserve hard code for guarantees.

When a wrong action has financial, legal, or safety consequences — like a large refund — you do not rely on a prompt. You enforce the rule deterministically with a hook or a programmatic precondition. Prompts guide; hooks guarantee.

So an agent is the right shape and critical rules are still enforced in code around it. The two are not in conflict.

# Prompt guidance is ~90% reliable — fine for routine routing.
# A hook is 100% deterministic — use it for critical rules:
#   block process_refund when amount > 500
#   block process_refund until get_customer returns a verified ID
# Outgoing-call hooks reject policy-violating actions before they run.

When a Pipeline Beats an Agent

Don't reach for an agent just because it feels modern. A fixed pipeline wins when:

The sequence of steps is known and stable.
You want predictable cost and latency (no open-ended looping).
You need control flow that is easy to test and debug.

Example: structured data extraction where you always extract, then validate, then format. The path never changes, so hard-coding it is the correct, robust choice. Adding agent autonomy here only adds nondeterminism and cost for no benefit.

When an Agent Is the Right Call

Choose an agent when the work is genuinely open-ended and the path depends on what is discovered along the way:

Bug investigation — grep entry points, read files, follow usages; you can't script the route in advance.
Multi-source research — a coordinator decomposes the question and delegates to subagents.
Customer support — one issue needs a lookup, another a refund, another an escalation.

In all of these, the next step depends on the last result. That dependency is exactly what an agentic loop handles and a fixed pipeline cannot.

system=("You are a debugging agent. Investigate the failing test "
        "and find the root cause.")
tools=[glob_tool, grep_tool, read_tool, bash_tool]
# The model adapts: Grep entry points -> Read files -> Grep usages
# -> Read consumers. The route is decided at runtime, not by you.

A Practical Checklist

Run any new task through this quick checklist:

One self-contained call? → simple prompt.
Known, fixed sequence of steps? → fixed pipeline.
Open-ended, path depends on results? → agent.
Critical rule (money / legal / safety)? → enforce it with a hook, whichever pattern you chose.

Default to the simplest pattern that works. Add autonomy only when the task truly needs it — and add deterministic enforcement wherever a mistake would be costly. That balance is what separates an architect from a tinkerer.

Quick Check

Test your decision-making on a realistic scenario.

Recap: Choosing Your Pattern

Key takeaways:

Simple prompt — self-contained, one call, no state (resend full history yourself).
Fixed pipeline — known, sequential steps; predictable, cheap, easy to debug.
Agent — open-ended path the model decides at runtime via the agentic loop.
The loop terminates on stop_reason == end_turn, never by parsing text; iteration caps are only a safety net.
Model decisions are probabilistic; enforce critical money/legal/safety rules with hooks or programmatic preconditions for deterministic guarantees.
Default to the simplest pattern that does the job.

Master this choice and the rest of agent architecture builds cleanly on top of it.

Frequently asked questions

Is the “When to Use an Agent” lesson free?

Yes — the full text of “When to Use an Agent” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “When to Use an Agent”?

Agents vs simple prompts vs fixed pipelines. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “When to Use an Agent” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect