---
title: "Claude Agent SDK and claude -p"
slug: "claude-agent-sdk"
category: "ai-agents"
tags: ["claude-agent-sdk", "claude-code", "headless", "ci", "ai-agents", "automation"]
status: "stable"
last_updated: 2026-10-01
summary: "Run Claude Code's agent loop from code with the Agent SDK (Python, TypeScript) or from scripts with claude -p; set tools, permissions, and settingSources."
related: ["[[ai-agents/claude-code]]", "[[ai-agents/claude-code-permissions]]", "[[ai-agents/claude-code-hooks]]", "[[ai-agents/claude-code-subagents]]", "[[ai-agents/claude-code-mcp]]", "[[ai-agents/reliable-agents-in-production]]", "[[tooling/github-actions]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript; `claude -p` is the same engine from the command line. Use it to embed an agent in an application you operate. For interactive work use the Claude Code CLI; to write the tool loop yourself against the raw API use the Client SDK; to have Anthropic host the agent use Managed Agents.

## Start with query()

Install `claude-agent-sdk` (Python 3.10 or later) or `@anthropic-ai/claude-agent-sdk` (Node 18 or later). Both bundle a native Claude Code binary. `query()` returns an async iterator of messages as Claude plans, calls tools, and finishes.

```python
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Review utils.py for crashes and fix them.",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob"],   # auto-approved
        permission_mode="acceptEdits",
    ),
):
    if isinstance(message, ResultMessage):
        print(message.subtype)
```

The TypeScript form takes the same options in camelCase (`allowedTools`, `permissionMode`). Set `ANTHROPIC_API_KEY` in the process environment; the SDK does not read `.env` files. Bedrock, Claude Platform on AWS, Vertex, and Foundry use `CLAUDE_CODE_USE_BEDROCK=1` and its siblings. Unless previously approved, Anthropic does not allow third-party products to offer claude.ai login for SDK agents, so use API keys.

## Pass tools and permissions explicitly

Give the agent the narrowest tool set: `Read`, `Glob`, `Grep` for analysis; add `Edit` to modify; add `Bash` for full automation. Choose the permission mode in code, because the starting mode can differ by version and plan; see [[ai-agents/claude-code-permissions]]. For programmatic control use a `canUseTool` callback or hook callbacks: a `PreToolUse` callback that returns `permissionDecision: "deny"` blocks a call and sends the reason to Claude.

## Decide what loads from disk

When `settingSources` is omitted, `query()` reads user, project, and local settings, `CLAUDE.md` files, and `.claude/` skills, agents, and commands, as the CLI does. Pass `settingSources: []` to run only on what you configure in code. Managed policy settings, `~/.claude.json`, auto memory, and claude.ai MCP connectors load regardless. For multi-tenant servers, give each tenant its own filesystem, set `settingSources: []`, and set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.

Extend the agent through `agents` (subagents; include `Agent` in `allowedTools`), `mcpServers`, `hooks`, and `skills`. Skills must exist as `.claude/skills/` files; there is no registration API. See [[ai-agents/claude-code-subagents]], [[ai-agents/claude-code-mcp]], and [[ai-agents/claude-code-hooks]].

## Script it with claude -p

```bash
claude --bare -p "Summarize README.md" --allowedTools "Read" --output-format json
```

- `--output-format` is `text`, `json` (includes `result`, session ID, and `total_cost_usd`, a client-side estimate), or `stream-json` (add `--verbose --include-partial-messages` for tokens).
- `--json-schema '<schema>'` with `json` output returns the validated object in `structured_output`.
- `--bare` skips hooks, skills, plugins, MCP servers, auto memory, and `CLAUDE.md`, so a script behaves the same on every machine; it never reads OAuth or keychain credentials, so set `ANTHROPIC_API_KEY` (or an `apiKeyHelper`), and it is the recommended mode for scripted calls. Without it, `claude -p` runs a repository's project hooks and `.mcp.json` servers even in a folder you never trusted, so use `--bare` on untrusted pull requests.
- Pass `--permission-mode` explicitly (`dontAsk` with exact `--allowedTools` for locked-down CI). Exit code is 0 on success and nonzero on failure.
- Continue with `--continue`, or capture `session_id` and pass `--resume <id>`. Piped stdin is capped at 10MB.

For GitHub workflows see [[tooling/github-actions]]. Harden any unattended agent with the checklist in [[ai-agents/reliable-agents-in-production]].

## Related

- [[ai-agents/claude-code]]
- [[ai-agents/claude-code-permissions]]
- [[ai-agents/claude-code-hooks]]
- [[ai-agents/claude-code-subagents]]
- [[ai-agents/claude-code-mcp]]
- [[ai-agents/reliable-agents-in-production]]
- [[tooling/github-actions]]