# Claude Code Agent SDK

> Claude Agent SDK purpose, installation, TypeScript/Python query usage, permissions, hooks, MCP, sessions and deployment boundaries.

URL: https://docs.passion8.cc/en/docs/claude-code/sdk
Language: en
Publisher: Passion8

Agent SDK exposes the Claude Code agent loop as Python and TypeScript libraries. Embed file reading, command execution, code editing and context management in services, CLIs, CI or background jobs.




Use the CLI for direct project work; use Agent SDK to embed these capabilities in products, automation and background services.




This page covers basics. See [API reference](https://docs.passion8.cc/en/docs/claude-code/sdk-api-reference) for TypeScript/Python, sessions, settings and migration; [agent features](https://docs.passion8.cc/en/docs/claude-code/sdk-agent-features) for the loop, settingSources, skills, subagents, todos and checkpoints; [capabilities](https://docs.passion8.cc/en/docs/claude-code/sdk-capabilities) for permissions, hooks, MCP, SessionStore, costs, OTEL, security and caching; [runtime patterns](https://docs.passion8.cc/en/docs/claude-code/sdk-runtime-patterns) for tools, prompts, streaming, structured output, search, approvals and commands; and [production deployment](https://docs.passion8.cc/en/docs/claude-code/sdk-production) for topology.

## When to use the SDK

| Requirement | Choose |
| --- | --- |
| Local interactive development and repository edits | Claude Code CLI |
| Run agents inside a web service or internal platform | Agent SDK |
| Automated fixes, reviews or migration in CI | Agent SDK or claude -p |
| Custom tools, approvals and session storage | Agent SDK |
| Pure model API calls | Claude Messages API |

## Installation





### TypeScript


```bash
npm install @anthropic-ai/claude-agent-sdk
```

The TypeScript SDK includes the platform Claude Code binary through an optional dependency; separate CLI installation is usually unnecessary.




### Python


```bash
pip install claude-agent-sdk
```

Python requires 3.10 or newer.







## Authentication

The official SDK supports API keys and cloud-provider authentication. For Passion8, point its Anthropic-compatible endpoint at the gateway:

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY"
```

For a direct Anthropic Console key, use:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```




Do not mix Claude subscription login with third-party products. Official guidance generally requires API key/provider authentication for third-party developers; do not resell or embed claude.ai subscription access in an agent product.




## Minimal examples

### TypeScript

```typescript title="agent.ts"
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Read the current directory and summarize this project's purpose.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk"
  }
})) {
  if ("result" in message) console.log(message.result);
}
```

Run:

```bash
npx tsx agent.ts
```

### Python

```python title="agent.py"
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Read the current directory and summarize this project's purpose.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="dontAsk",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())
```

Run:

```bash
python agent.py
```

query() returns an async iterator. Items may be system or assistant messages, tool calls, tool results or the final result. Stream them to a UI or collect them for processing.

## Common options

| Option | TypeScript | Python | Purpose |
| --- | --- | --- | --- |
| Preapproved tools | `allowedTools` | `allowed_tools` | Preapprove tool use |
| Permission mode | `permissionMode` | `permission_mode` | acceptEdits, plan and others |
| System prompt | `systemPrompt` | `system_prompt` | Custom agent role |
| MCP | `mcpServers` | `mcp_servers` | External tools |
| Hooks | `hooks` | `hooks` | Intercept before/after tools |
| Working directory | `cwd` | `cwd` | Agent execution directory |

## Permission modes

| Mode | SDK purpose |
| --- | --- |
| `default` | Supply an approval callback |
| `acceptEdits` | Automatically accept file edits |
| `plan` | Read-only exploration without source changes |
| `dontAsk` | Deny actions outside the allowed tools |
| `auto` | TypeScript safety classifier |
| `bypassPermissions` | Sandboxed CI or isolated environments only |

Start production agents with dontAsk or plan, expanding tool access for the task as needed.

## Built-in tools

Agent SDK can use Claude Code's core tools directly:

| Tool | Purpose |
| --- | --- |
| Read | Read files |
| Write | Create files |
| Edit | Precise file edits |
| Bash | Run commands |
| Glob | Find files |
| Grep | Search content |
| WebSearch | Search the web |
| WebFetch | Fetch pages |
| Monitor | Watch background script output |
| AskUserQuestion | Request clarification or approval |

## Hooks and MCP

The SDK also supports Claude Code extensions:

- Hooks: record, block or validate at PreToolUse, PostToolUse, Stop and other events.
- MCP: connect databases, browsers, internal APIs and project-management systems.
- Subagents: isolate subtasks in specialized agents.
- Sessions: save and restore conversation context.
- Prompt caching: inspect cache read/write tokens and control TTL.

## Production recommendations

| Risk | Recommendation |
| --- | --- |
| Unbounded runs | Set timeouts, turn limits and budgets |
| Too many tools | Use tool search or expose only task-relevant tools |
| Excessive permissions | Default to dontAsk and allow tools individually |
| Tenant leakage | Isolate working directory, environment and session storage per user |
| Uncontrolled costs | Record cache_creation_input_tokens and cache_read_input_tokens |
| Difficult output parsing | Use structured output or JSON schema |

See [production deployment](https://docs.passion8.cc/en/docs/claude-code/sdk-production) for a complete checklist. For persistent conversations, queues, images and plugins, continue to [streaming and plugins](https://docs.passion8.cc/en/docs/claude-code/sdk-streaming-plugins).

## Official references

- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview.md)
- [Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md)
- [TypeScript SDK reference](https://code.claude.com/docs/en/agent-sdk/typescript.md)
- [Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md)
- [Agent SDK permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)

## Related pages



- [Agent SDK API reference](https://docs.passion8.cc/en/docs/claude-code/sdk-api-reference): TypeScript/Python installation, query, ClaudeSDKClient, session APIs and migration.
- [Agent SDK streaming and plugins](https://docs.passion8.cc/en/docs/claude-code/sdk-streaming-plugins): Streaming input, single messages, plugin loading, namespaces and caching.
- [Agent SDK runtime patterns](https://docs.passion8.cc/en/docs/claude-code/sdk-runtime-patterns): Custom tools, system prompts, structured output, tool search and approvals.