Firstpass v0.2.1
DocsGuaranteeBenchmarksCLIGitHub

Docs / How Agents Talk to Models / Three client shapes

Part A · The core pathModule 6 of 13

Three client shapes

The same wire powers three very different agents. A coding agent (Claude Code) — long multi-turn sessions, heavy tools; cost is transcript × call count. A headless agent — CI/cron, short loop run over many items; cost is volume × per-run. An SDK app — you own the loop, so you control all three levers directly. What changes isn't the wire, it's who drives the loop and what dominates the bill.
Three client shapes on the same wire: Interactive coding agent (loop driven by human plus tool, cost = growing transcript × tool-call count), Headless CI/cron agent (loop driven by script or scheduler, cost = per-run × volume), and SDK app (loop driven by you, cost = your choices on all three levers). Same wire underneath — three different cost shapes. INTERACTIVE Coding agent (e.g. Claude Code) Drives loop human + tool Cost driver transcript × tool calls grows on every round-trip HEADLESS CI / cron (pipeline, scheduler) Drives loop script / scheduler Cost driver per-run × volume small run, paid thousands of times SDK APP Your SDK app (you own the loop) Drives loop you Cost driver your choices · all 3 levers most tuning headroom, most rope POST /v1/messages — stateless · tokens · tools · cache
Same HTTP wire, three cost shapes: coding agents pay for long tool-heavy transcripts, headless agents pay per-run × volume, SDK apps pay for whatever you choose to send.

The same wire — stateless calls, tokens, tools, cache — powers very different agents. What changes is who drives the loop and what dominates the bill:

interactive

Coding agent

A human-in-the-loop tool like Claude Code. Long multi-turn sessions, heavy tool use, subagents. Cost is dominated by the growing transcript × the tool-call count: re-read across dozens of round-trips. Prime candidate for caching.

headless

Automation / batch agent

CI jobs, cron, pipelines — no human waiting. Usually a fixed, shorter loop per item, run over many items. Cost is dominated by volume × per-run: the per-run bill is small, but you pay it thousands of times.

sdk

Your own SDK app

You own the loop with the Anthropic/OpenAI SDK. You decide how much history to resend, how many tools to attach, and whether to cache — so you control all three cost levers directly. Most tuning headroom, most rope.

ShapeLoop driven bySingle vs multi-turnWhat dominates cost
Coding agentThe tool, with a humanLong multi-turn + toolsRe-read transcript × many tool calls
Headless agentA script / schedulerOften short, repeatedRun volume × per-run cost
SDK appYouWhatever you buildYour choices on all three levers

Headless, end to end: the same task as a CI job

Take the exact /orders fix and run it with no human — a CI job on every pull request: “if this endpoint reads a field without a presence check, add the guard and a test.” Same wire, same tool loop as the interactive session, but two things change. There's no conversation — the job fires one bounded agent run and exits, so the transcript never grows past the task. And it runs over volume — 200 pull requests a day is 200 independent runs. The per-run bill is small; the line item is per-run × volume.

bash
# headless: one bounded agent run per PR, no human, no growing chat
for pr in $(gh pr list --json number -q '.[].number'); do
  agent run --task "guard missing fields + add test" --pr "$pr"   # ≈6 model calls, then exits
done
# cost is NOT one long session — it's (per-run bill) × (how many PRs)
≈6
model calls in one bounded /orders run
×200
PRs/day — the volume multiplier
≈$0.13
per run on sonnet (illustrative)
≈$26
/day = per-run × volume (illustrative)
One safe reflex, one big bill Across all three shapes, the tempting default is “send every call to the strongest model, to be safe.” That's the single choice that makes an afternoon of agent work bill like a research run — and in the headless case, multiplies straight into the volume: the top tier on 200 runs a day, most of which were easy. That reflex is exactly what Part B is about.
Same wire, three cost shapes: coding agents pay for long tool-heavy transcripts, headless agents pay per-run × volume, SDK apps pay for whatever you choose to send.