Prompt Chaining in Python: A Runnable Claude Tutorial (2026)

Quick Answer

Prompt chaining is an agentic workflow pattern where you split one task into a fixed sequence of LLM calls, feeding each step's output into the next, and put a validation gate between steps that halts the chain before it wastes tokens on a bad intermediate result. As of July 2026 it is the first and simplest of the five patterns in Anthropic's "Building Effective Agents" taxonomy, and it beats a single mega-prompt whenever a task has clear, checkable stages. This tutorial builds a runnable prompt chaining pipeline in Python with the Claude API, including a pure-Python gate and a cheap LLM gate.

What is prompt chaining?

Prompt chaining decomposes a task into fixed steps. Each step is its own LLM call with a narrow job, and the output of step N becomes part of the input to step N+1. Between steps you place a gate: a programmatic check that decides whether the chain continues or stops.

The pattern is deliberately not an agent. An agent decides its own next action at runtime; a chain runs a path you defined in advance. That predictability is the point. When you already know the steps, hard-coding them is cheaper, faster, and far easier to debug than handing control to a model. This tutorial is the deep dive on pattern one from our overview of agentic-workflow-patterns-python, where prompt chaining sits alongside routing, parallelization, orchestrator-workers, and evaluator-optimizer.

Anthropic's engineering write-up "Building Effective Agents" (2026) frames chaining as the default starting point: reach for it before you reach for anything that looks like an agent. The neutral Prompt Engineering Guide entry on prompt chaining (2026) makes the same case from the prompting side.

Prompt chaining vs one big prompt vs an agent

Picking the wrong altitude is the most common mistake. Use this to place your task.

If you can draw the flow on a whiteboard as a straight line with a couple of decision diamonds, it is a chain. If the arrows loop back and branch based on what the model finds, you are in agent territory.

Setup

You need the Anthropic Python SDK and an API key. Install and export:

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

One thin helper wraps every call so the rest of the code stays readable. Note the two model tiers: a low-cost model for cheap steps and gates, a mid-tier model for the real generation. As of July 2026 those are Haiku 4.5 and Sonnet 5 respectively; check the Anthropic Messages API docs (2026) for the current model identifiers and the pricing page for per-token rates.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

CHEAP = "claude-haiku-4-5-20251001"   # gates + light steps
STRONG = "claude-sonnet-5"            # real generation

def call(model: str, prompt: str, max_tokens: int = 1024) -> str:
    msg = client.messages.create(
        model=model,
        max_tokens=max_tokens,
        messages=[{"role": "user", "content": prompt}],
    )
    return msg.content[0].text.strip()

The task for this tutorial: turn a one-line feature description into a clean, sectioned changelog entry. Three steps, two gates.

the first link in the chain

The first call produces a plain outline. Keep the prompt narrow. A step that tries to do two jobs is where chains break.

def make_outline(feature: str) -> str:
    prompt = (
        "Turn this feature description into a changelog outline.\n"
        "Return 3 to 5 lines, each starting with '- '. No prose.\n\n"
        f"Feature: {feature}"
    )
    return call(CHEAP, prompt)

The gate that saves tokens

Here is the part the definitional articles skip: the gate is not another LLM call. The cheapest, most reliable gate is plain Python that inspects the previous output and raises before you spend money on the next step.

class GateError(Exception):
    """Raised when an intermediate result fails its check."""

def gate_outline(outline: str) -> list[str]:
    lines = [ln.strip("- ").strip() for ln in outline.splitlines() if ln.strip().startswith("- ")]
    if not (3 <= len(lines) <= 5):
        raise GateError(f"Expected 3-5 bullets, got {len(lines)}")
    if any(len(ln) < 8 for ln in lines):
        raise GateError("A bullet is too short to expand")
    return lines

If step 1 returns garbage, gate_outline raises immediately. You never pay for step 2 on a broken outline. On a chain of three Sonnet calls, catching a failure at gate one instead of at the end is the difference between one wasted cheap call and three wasted expensive ones. That token math is the entire reason gates exist.

expand each validated step

Now the strong model does the real work, once per validated bullet.

def expand(bullet: str) -> str:
    prompt = (
        "Write one changelog entry (2 sentences, past tense, user-facing) "
        f"for this item. No heading, no bullet.\n\nItem: {bullet}"
    )
    return call(STRONG, prompt)

The LLM gate: when a check needs judgment

Some checks cannot be expressed as len() or a regex. "Is this entry actually user-facing and free of internal jargon?" needs judgment, so the gate itself becomes a cheap LLM call that returns a hard PASS or FAIL. This is the same technique as a full evaluator, applied narrowly; if you want the deep version, see our tutorial on llm-as-a-judge.

def gate_tone(entry: str) -> bool:
    verdict = call(
        CHEAP,
        "Reply with exactly PASS or FAIL. PASS if the text is user-facing "
        "and free of internal jargon or ticket numbers; FAIL otherwise.\n\n"
        f"Text: {entry}",
        max_tokens=5,
    )
    return verdict.upper().startswith("PASS")

Keep LLM gates binary and cheap. A gate that returns a paragraph of feedback is no longer a gate; it is the evaluator-optimizer pattern, which loops, and that is a different tool.

Put the chain together

The full pipeline wires the steps and gates in order, with a single retry on the tone gate so one bad expansion does not kill the run.

def changelog(feature: str) -> str:
    outline = make_outline(feature)
    bullets = gate_outline(outline)          # gate 1: structural, pure Python

    entries = []
    for bullet in bullets:
        entry = expand(bullet)               # step 2: strong model
        if not gate_tone(entry):             # gate 2: LLM judgment
            entry = expand(bullet + " (plain user language, no jargon)")
        entries.append(f"- {entry}")

    return "## Changelog\n\n" + "\n".join(entries)

if __name__ == "__main__":
    print(changelog("Added SSO via SAML and per-seat billing to the admin panel"))

Run it. You get a sectioned changelog where every entry passed a structural gate and a tone gate, and a malformed outline would have stopped the run before a single Sonnet call. That is prompt chaining: fixed steps, checkable outputs, gates that fail fast.

When prompt chaining is the wrong tool

Chaining is not free. Every added step adds latency and a place for errors to compound. Do not reach for it when a single well-written prompt does the job, and do not use it to fake an agent. If your gates keep needing to send work back to an earlier step, you have discovered a loop, and a chain cannot express a loop cleanly. That is the signal to move up to evaluator-optimizer or a real agent.

The pattern is also model-agnostic. The same three-step-two-gate shape works against OpenAI's or any other chat completions API; only the call() helper changes.

FAQ

What is the difference between prompt chaining and chain-of-thought prompting?
Chain-of-thought happens inside one LLM call: you ask the model to reason step by step in a single response. Prompt chaining happens across multiple calls: each step is a separate request with its own prompt and an optional gate between them. Chain-of-thought is a prompting trick; prompt chaining is a workflow architecture.

When should I use prompt chaining instead of a single prompt?
Use it when the task has two or more stages whose intermediate output you can check, or when one giant prompt produces unreliable results. If the task is a single clean transformation with no meaningful middle, keep it as one prompt.

What are the disadvantages of prompt chaining?
More calls mean more latency, more cost, and compounding errors if a bad early output slips past its gate. It also cannot express loops. If your flow needs to revisit earlier steps based on later results, chaining is the wrong pattern.

What is a gate in prompt chaining?
A gate is a check between two steps that decides whether the chain continues. The best gates are plain code (length, schema, regex). When a check needs judgment, use a cheap LLM call that returns a binary PASS or FAIL.

Is prompt chaining an AI agent?
No. A chain runs a path you defined in advance; an agent decides its own next action at runtime. Chaining is deliberately more constrained, which makes it cheaper and easier to debug.

Does prompt chaining work with models other than Claude?
Yes. The pattern is architecture, not vendor-specific. Swap the API client in the call() helper and the chain runs against any chat model.

Limitations and open questions

• The tone gate here uses a single cheap call with no calibration. In production you would measure its false-pass rate against a labeled set before trusting it, the same discipline covered in the LLM-as-a-judge tutorial.
• The pipeline retries the tone gate exactly once. A principled retry budget (and what to do when the retry also fails) is workload-specific and is not solved here.
• Gates that start returning feedback rather than a verdict are a smell that the task wants evaluator-optimizer, not chaining. Where exactly that line sits is a judgment call this tutorial does not fully resolve.
• Model identifiers and pricing tiers change. The CHEAP and STRONG constants are correct as of July 2026; re-check the Anthropic docs before shipping.