Agent SDK
Programmatic access
What the Claude Agent SDK Is
The Claude Agent SDK is a library that runs the same agent you use in the terminal directly from your Python (package claude-agent-sdk) or TypeScript (package @anthropic-ai/claude-agent-sdk) code, without an interactive conversation. Where the CLI is something you open by hand and chat with, the SDK is called from a script: you pass a prompt and an options object (working directory, model, permission mode), and the agent reads files, edits them, runs commands, and streams messages back as it works. That is what turns Claude Code from a manual tool into a building block for automations, CI/CD pipelines, and assistants embedded inside a product.
How it works, by example
The Python and TypeScript blocks above show the minimal flow: you call the query() function with a text task like “fix the failing tests in auth.ts” and an options object pointing it at a project path. query() is an async generator — instead of returning one result it streams message objects (AssistantMessage, ResultMessage, and others) as the agent works through its steps. You iterate over them with async for (Python) or for await (TypeScript); the final ResultMessage carries the result and token-usage stats. There is no { output, cost } return object — the data arrives as a stream. The commands in the non-interactive mode block do the same from a terminal: -p (a.k.a. --print) runs the task once and exits, --model picks the model, --permission-mode acceptEdits disables confirmations, and --mcp-config wires in external tools over MCP. That suits one-off scripts and cron jobs where full SDK code is overkill.
The GitHub Actions config shows how to embed the agent into automated review: on every opened or updated pull request the workflow checks out the code and runs the official action, handing it a review prompt and two secrets — the GitHub token and the ANTHROPIC_API_KEY. Keys always live in repository secrets, never in code. The main pitfalls with the SDK: always cap iterations with the maxTurns option so the agent cannot loop and burn budget; set permissionMode: ‘acceptEdits’ so it runs without prompts; handle timeouts and errors, because in unattended mode nobody can step in; and watch token usage from the streamed ResultMessage, since running on every PR adds up fast. Prototype the prompt in the CLI first, then move to the SDK once the workflow is stable and worth repeating.
CLI (Interactive)
- • Interactive development
- • Debugging and exploration
- • One-off tasks
- • Learning and experiments
SDK (Programmatic)
- • CI/CD automation
- • Batch processing
- • App integration
- • Custom workflows
The -p / --print flag runs Claude Code without an interactive conversation — it executes the task and exits:
# Non-interactive (print) mode - run once and exit claude -p "Fix all TypeScript errors" # With specific model claude -p "Add tests for UserService" --model sonnet # Auto-approve edits (no permission prompts) claude -p "Refactor the auth module" --permission-mode acceptEdits # With MCP servers claude -p "Query database for users" --mcp-config ./mcp.json
-p / --printNon-interactive, one-shot run--modelModel selection--permission-modee.g. acceptEdits — no prompts--mcp-configWire in MCP servers# pip install claude-agent-sdk
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project",
permission_mode="acceptEdits", # auto-approve edits, no prompts
max_turns=10,
)
# query() is an async generator: it streams messages as the agent works
async for message in query(
prompt="Fix the failing tests in auth.ts",
options=options,
):
# AssistantMessage, ResultMessage, etc. arrive here
print(message)
anyio.run(main)Integrate Claude Code into CI/CD via GitHub Actions:
name: Code Review with Claude
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Claude Code Review
uses: anthropic/claude-code-action@v1
with:
prompt: |
Review this PR for:
- Code quality issues
- Security vulnerabilities
- Performance problems
Provide specific feedback with line numbers.
github-token: ${{ secrets.GITHUB_TOKEN }}
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}Automatic PR Code Review
Run review on every PR
Test Generation
Auto-write tests for new code
Documentation
Update docs on changes
DB Migrations
Generate migrations from description
SDK Usage Tips
- 1.Cap iterations with the maxTurns option
- 2.Handle errors and timeouts
- 3.Read the final result and token usage from the streamed ResultMessage
- 4.Store API keys in secrets
Frequently asked questions
What is the difference between the Claude Code SDK and the CLI?
The CLI is an interactive mode you open by hand and chat with, ideal for debugging and one-off tasks. The SDK is a programmatic interface: you call the same agent from Python or TypeScript code, pass a prompt and a working directory, and get the result as a structured object. Use the SDK for automations, CI/CD, and embedding the agent into applications where an interactive conversation is not possible.
How do I run Claude Code in headless mode?
Use the --headless flag to disable interactive confirmations together with --prompt for the task, for example: claude --headless --prompt "Fix all TypeScript errors". Additionally --model selects the model (such as Sonnet), --output writes the result to a file, and --mcp-config wires in external tools over MCP. This suits scripts and cron jobs where full SDK code is overkill.
How do I integrate Claude Code into GitHub Actions for code review?
Define a workflow triggered on pull_request events (opened, synchronize). The steps check out the code with actions/checkout and run the official anthropic/claude-code-action, passing a review prompt plus two secrets: GITHUB_TOKEN and ANTHROPIC_API_KEY. Keys always live in repository secrets, never in code. The agent then reviews each PR automatically for quality, security, and performance.
How do I control costs when using the Claude Code SDK?
Cap the agent's iterations with --max-turns so it cannot loop and burn budget. Track the cost field on the result object, which reports each run's dollar cost. In automated scenarios such as reviewing every PR, spend adds up fast, so handle timeouts and errors and estimate the volume of calls in advance.
This lesson is part of a structured LLM course.
My Learning Path