The Agent SDK and headless automation

Running the same harness programmatically, and in CI where nobody can answer a prompt.

5 min read · Lesson 11 of 11 in this domain

The Claude Agent SDK is Claude Code packaged as a library: the same agent loop, built-in tools, context management, hooks, subagents, permissions and sessions, driven from your own code rather than a terminal. You host it. That makes it the right choice when you want a batteries-included coding or filesystem agent inside your own service — as distinct from the Messages API tool runner, which loops over tools you define and ships no built-in tools at all. For CI the constraint is different and simpler: there is no TTY and no human, so you run non-interactively and emit machine-readable output the pipeline can branch on. The temptation there is to switch off permissions so nothing can ever block the build; that is precisely backwards, because CI is the context with no human supervising.

• The Agent SDK gives you the full Claude Code harness — built-in Read/Write/Edit/Bash/Glob/Grep plus MCP, subagents and hooks — hosted by you.
• The Messages API tool runner is a different thing: it drives a loop over tools you define, with no built-in tools and no filesystem access.
• For CI, run non-interactive print mode and parse a structured JSON output format to decide pass or fail.
• Scripting keystrokes into an interactive session is brittle: CI runners have no TTY.
• Do not blanket-bypass permissions in automation — it removes the safety boundary exactly where nobody is watching.
• Settings precedence still applies in CI, so managed policy and committed project settings both take effect on the runner.

Source: Claude Docs — Agent SDK · Independent study aid, not affiliated with or endorsed by Anthropic.