Why this lesson exists
Most wasted effort in this space comes from using the wrong surface — hand-writing API calls for a one-off question, or using a chat window for a job that needs to run two hundred times. There is a clean decision rule. This lesson gives it to you.
Four surfaces, one model
Everything below talks to the same deepseek-flash. What differs is who holds the state, who holds the tools, and who holds the loop.
| Surface | State lives in | Tools | Good for | Cost shape |
|---|---|---|---|---|
| Chat web / app |
The product | Whatever the product offers | Thinking, drafting, one-off questions, exploring an idea | Flat subscription or free |
| Direct API your code |
You | None — you supply everything | Repeatable jobs, integration into an existing system, precise control | Per token |
| Single-shot CLI print mode |
You | Minimal | Scripted one-off transformations, piping, shell automation | Per token, tiny |
| Agent harness Reasonix and similar |
The harness | Files, shell, search, web | Building things, multi-step work, anything with a filesystem | Per token, cache-dominated |
The decision rule
Ask these four questions in order. Stop at the first yes.
- Is this a one-time thought, not a deliverable? Use chat. Reaching for an API to ask a question is a category error, and it is a common one for people who have just learned the API.
- Will it run more than a handful of times, or inside an existing system? Use the direct API. You want the logic in code, versioned, testable, with your own error handling.
- Is it a single transformation over a file or a pipe, invoked from a shell? Use a print-mode CLI. No session, no state, output to stdout.
- Does it need to read files, run commands, and iterate until something works? Use an agent harness. This is the only surface that can close the loop on its own.
The dividing line that matters most: does the work require iteration against reality? If the model needs to write a file, run it, read the error, and try again — you need a harness. If it just needs to produce text you will inspect — you do not.
Why the harness exists at all
A bare API call has one round trip. It receives text and returns text. Whatever you want done with a filesystem, a command runner, or a test suite, you have to do.
An agent harness supplies four things the API does not:
- A tool loop. The model can call a tool, see the result, and decide what to do next — repeatedly, without you relaying messages.
- Filesystem access. Read, write, search, and diff against real files rather than pasted text.
- Command execution. Run the test, read the failure, fix it.
- Context management. Decide what to keep in the window, what to summarise, and what to drop. At scale this is the hardest of the four.
Recall Lesson 4's most instructive benchmark row: the same model scored 36.8 on a hard benchmark without tools and 63.9 with them. That gap is the harness. It is frequently a bigger lever than model choice.
The harness is where the risk lives
A harness that can write files and run shell commands can also delete files and run the wrong command. Every serious harness therefore has a permission model, and every serious harness has a default that is more conservative than you want. Module 7 covers this properly — including the specific failure where an unattended run composes a perfect answer and then reports that every write was blocked.
Mixing surfaces is normal and correct
You are not choosing one. A realistic workflow uses three:
- Chat while you are still deciding what to build. Fast, no setup, and there is no reason to pay per token to think out loud.
- Harness for the build. It holds the loop against a real filesystem.
- Direct API for whatever turned out to be recurring — the classification step, the summariser, the data pull. You learned the shape during the build; now it belongs in code.
The migration direction is one-way and worth naming: things move from chat to harness to API as they become more repeatable. They rarely move back.
Checkpoint
- What is the single question that most reliably separates API work from harness work?
- Your team asks you to "add AI summarisation" to an existing service. Which surface?
- Why is using the API to answer a one-off question a category error?
- Name the four things a harness supplies that a bare API call does not.
Answers
- Does the work need iteration against reality — writing, running, reading failure, retrying? If yes, harness.
- The direct API. It is code inside a system, run repeatedly, and needs your error handling.
- You pay per token and write integration code to get what a chat window gives you for free.
- A tool loop, filesystem access, command execution, and context management.
Exercise: sort your own workload
List ten things you actually want AI help with over the next month. For each, write the surface and one sentence of justification using the four-question rule.
Then find the two entries where you are least confident. Run those two as a deliberate experiment on the cheaper surface first. If the cheaper surface is not enough, the upgrade is now evidence-based rather than assumed — and you will have learned where your own dividing line actually sits, which is often not where you would have guessed.
Next
Module 2 is complete. You can call the model, control what it costs, and pick the right surface. Module 3 is where output quality starts to compound: prompting DeepSeek on its own terms.