Capstok — learn by doing

Why this matters

Agents are the wrong tool for a lot of work that the AI hype suggests they're right for. If the task is deterministic, an agent adds latency and unpredictability without improving anything. If user expectations require strict guarantees (legal, financial transactions), the open-loop nature of agents fights you. If cost matters and the task is high-volume, agents 3-5x your bill vs a workflow. The discipline: default to workflow; reach for agent only when the task genuinely needs runtime decisions.

Demo

Use workflow when: (1) the steps are deterministic. (2) you need strict latency SLAs. (3) you need predictable cost. (4) the task is high-volume and price-sensitive. (5) compliance requires reproducibility. Use agent when: (1) the tool choice depends on the user's request. (2) the path through tools varies (retry, branch, dead-end). (3) the task is exploratory (research, debugging). Most production AI work is the first list, not the second.

Try it yourself

Audit each AI feature you've shipped. Mark each: workflow or agent? Then ask: is the marking correct or marketing?
Take one feature you call an agent. Convert it to a workflow (fixed chain). Measure: did anything get worse?
For the genuinely agentic cases, document WHY: which step's path can vary? What signal in the user's request changes it?
Resist 'just use an agent'. Agents are powerful but expensive — match the pattern to the task.

Prompt your AI

Use these three in order. Each builds on the one before.

1. Basics & terminology

Name 3 use cases where an agent is the right shape and 3 where it's the wrong one.

2. Why it works (the mechanism)

Walk me through the cost calculus: a workflow takes 2 LLM calls; an agent for the same task takes 4-6. What does that translate to at 1M queries/day?

3. Advanced — application & what's next

I have a customer-support flow currently built as a 6-step agent. p99 latency is 12s, cost is $0.06/query. Help me decide: keep agentic, or rebuild as a deterministic workflow with a 'fallback to agent' tier?

References

Chat about this lesson

# When workflow is right
def get_user_summary(user_id):
    user = db.get(user_id)                          # not LLM
    recent = db.recent_orders(user_id, limit=10)    # not LLM
    summary = generate_summary(user, recent)        # 1 LLM call
    return summary
# Deterministic, fast (~500ms), cheap (~$0.005).

# When agent is right
def help_me_debug_this_error(error_msg, codebase):
    # Steps depend on the error — might need to grep code,
    # read docs, search SO, look at git blame, run tests.
    # No fixed path.
    return run_debugging_agent(error_msg, codebase, max_steps=10)
# Variable cost ($0.05-$0.50), variable latency (10-60s), high value if it works.

# Anti-pattern: an agent for a workflow
def classify_ticket_with_agent(ticket):
    # gives the model "search_kb" and "ask_human" tools
    # but really we just want CLASSIFY -> RETURN
    # so we end up paying agent overhead for a 1-call task.
    ...

# This is a workflow:
def classify_ticket(ticket):
    return client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=20,
        system="Classify into: billing, technical, sales, other. Reply one word.",
        messages=[{"role": "user", "content": ticket}],
    ).content[0].text.strip()

Run: python3 main.py

When NOT to build an agent