Why I Deleted the Anthropic SDK From My Workflow

I had a 50-case benchmark to run. My first instinct was to wire it through the Anthropic SDK. That would have been wrong.

The benchmark was a router accuracy test for my Claude Code skill corpus: 50 adversarial prompts, each one dispatched to a sub-agent that reads the full 103-skill description block and returns a ranked top-3 skill match with a rationale. I wanted to know whether my corpus would route correctly at scale. My default assumption was that the Anthropic SDK was the orchestration tool for this kind of multi-agent workload. I was wrong about where the work actually lives.

The procurement angle

Here is what I did not think through at the start. The Anthropic SDK pulls from your console.anthropic.com credit balance. That is a separate billing relationship from your Claude subscription.

For a solo operator or a small consultancy, that means two invoices, two balance top-ups, two places where a bill can go to zero at 2am and take your workflow down with it. If you are an ACMA-type who reconciles accounts at month end, it also means two line items with different cost drivers: subscription is flat, API credit is consumption-based and non-linear.

Most operators I speak with have not consciously separated these two billing relationships. They assume the Claude subscription and the Anthropic SDK credit are the same pot. They are not.

There is also a practical setup cost. Using the SDK inside a Claude Code session requires an ANTHROPIC_API_KEY in the subprocess environment. Claude Code's subprocess environment is intentionally sandboxed: no key is present by default. Getting one in there means either relaxing the sandbox or injecting a secret into the environment at launch, which introduces a maintenance surface that has nothing to do with the orchestration work you actually want to do.

Setting up SDK-based orchestration inside a Claude Code workflow means accepting a second procurement decision, a second credential management problem, and a second billing relationship, none of which you signed up for when you opened Claude Code.

The architectural angle

When your orchestration lives inside Claude Code, the correct tool is sub-agent dispatch using the Agent tool with subagent_type.

A sub-agent dispatched this way does four things that the SDK path cannot easily replicate inside Claude Code. It inherits the session's context model. It returns a structured result directly to the parent agent. It writes telemetry events into the same session JSONL that every other session event lands in. And it bills against the same subscription quota that resets on a fixed interval, not against a credit balance that drains silently.

The SDK is not a bad tool. It is the right tool for workloads that have to run outside Claude Code: long-running cron jobs, web application backends, anything with its own runtime that does not share session context with a Claude Code session. The two paths are not substitutes. They are complements with non-overlapping use cases.

The error I nearly made was treating them as interchangeable because both call Claude models. They do not interoperate the way you expect. The Claude Code subprocess environment is intentionally sandboxed. There is no ANTHROPIC_API_KEY in it. Wiring the SDK into that environment requires breaking the sandbox, which is the opposite of what I want.

The 25-agent quota cliff

I hit a quota cliff at 25 cumulative sub-agents, roughly 2.1 million cumulative tokens into the 50-case run. The session paused with an 18-minute reset timer.

The cliff was a feature. The subscription quota is a rate-limit, not a credit-depletion. At the end of 18 minutes, the quota reset and the run continued cleanly from where it stopped. I knew exactly where it stopped because I had written a subagent_dispatched telemetry event before each agent fired and a subagent_completed event after each returned. The recovery was a 4-case retry with no data loss.

Via the SDK, the same event would have looked different. A credit balance does not reset. It depletes. The equivalent interruption would have been a failed API call, likely at an inconvenient time, with no structured recovery path unless I had built one explicitly. The built-in reset behavior of subscription quota is, in practice, a reliability property that I had not consciously valued until it saved me.

Telemetry-first dispatch is also much simpler to wire in the sub-agent path. The Agent tool flow is synchronous enough that writing events before and after each call is a natural checkpoint. In the SDK flow, you are managing async calls, response handlers, and your own event emitter, which compounds the implementation surface for something that should be a 6-line Python pattern.

The 30-second decision rule

If your orchestration lives inside Claude Code, default to sub-agent dispatch. No separate billing. No separate API key. No broken sandbox. The Agent tool with subagent_type is the native path.

If your workload has to run outside Claude Code, you need the SDK. That is the right call for scheduled pipelines, server-side integrations, and anything that cannot share session context with a Claude Code session. A nightly data-processing job that runs on a server with no Claude Code session attached to it: SDK. A 50-case benchmark that fires inside an active Claude Code session with access to all your skill files and session context: sub-agent dispatch.

The question to ask takes about 30 seconds: does this workflow exist inside a Claude Code session, or does it need its own runtime? The answer determines the tool. There is no overlap, and there is no scenario where you should be running both paths for the same workload. Two paths for the same job doubles your operational overhead and halves your observability, because events from each path land in different places.

What I would tell a small consultancy starting today

Do not set up the SDK for in-session orchestration. You will pay for it twice: once in credit top-ups you did not budget for, and once in the complexity of managing two billing relationships for what is, at its core, one subscription-level workflow. Start with sub-agent dispatch, measure what you fire with telemetry events, and let the SDK wait until you have a workload that genuinely needs to run outside Claude Code. That day will come. It just is not today.

Part of the Operating Principles series from KG Consultancy.