Cuándo usar un agente

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Test your decision-making on a realistic scenario.

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.