# Claude Agent Sdk

> Claude Agent SDK complete guide -- ClaudeAgentOptions, custom tools via @tool decorator, MCP servers, permission modes, sub-agents, extended thinking, and tool use API.

- Skill: `leolin990405/claude-agent-sdk` (Agent Skill)
- Install (CLI): `npx get-skill add leolin990405/claude-agent-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leolin990405/claude-agent-sdk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: LeoLin990405 (https://skillmd.com/u/leolin990405)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/leolin990405/claude-agent-sdk

---


# Claude Agent SDK

## ClaudeAgentOptions (Python)

```python
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    system_prompt="You are a code review expert.",
    allowed_tools=["Read", "Glob", "Grep", "Bash(npm test *)"],
    disallowed_tools=["WebFetch"],
    permission_mode="default",         # default|acceptEdits|dontAsk|bypassPermissions|plan
    max_turns=20,
    cwd="/path/to/project",
    mcp_servers={"github": {"command": "npx", "args": ["-y", "@mcp/server-github"]}},
    env={"GITHUB_TOKEN": "xxx"},
    include_partial_messages=True,
    fork_session=False,                # True = isolated context
)

client = ClaudeSDKClient()
async for event in client.query("Review the auth module", options=options):
    if event.type == "text":
        print(event.text)
    elif event.type == "tool_use":
        print(f"Using: {event.tool_name}")
```

## Custom Tools via @tool Decorator

```python
from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("search_jira", "Search Jira issues", {
    "query": {"type": "string", "description": "JQL query"},
    "limit": {"type": "integer", "description": "Max results", "default": 10}
})
def search_jira(args: dict) -> dict:
    results = jira_client.search(args["query"], max_results=args.get("limit", 10))
    return {"content": [{"type": "text", "text": format_issues(results)}]}

server = create_sdk_mcp_server(
    name="jira-tools", version="1.0.0",
    tools=[search_jira]
)
```

### TypeScript

```typescript
import { tool, createSdkMcpServer } from "claude-agent-sdk";

const searchJira = tool(
  "search_jira", "Search Jira issues",
  { query: { type: "string" }, limit: { type: "integer", default: 10 } },
  async (args) => ({ content: [{ type: "text", text: "Results..." }] })
);

const server = createSdkMcpServer({
  name: "jira-tools", version: "1.0.0",
  tools: [searchJira]
});
```

## Tool Use API

### Tool Definition
```json
{
  "name": "get_weather",
  "description": "Get current weather at a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "City and state"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location"]
  }
}
```

### Flow
```
Request → Claude returns tool_use blocks (stop_reason: "tool_use")
  → Execute tools locally
  → Return tool_result blocks
  → Claude generates final response
```

### Parallel Tool Use
Claude can return multiple `tool_use` blocks. Return ALL `tool_result` blocks in a single user message.

### tool_choice
- `{"type": "auto"}` — default, Claude decides
- `{"type": "any"}` — must use a tool
- `{"type": "tool", "name": "get_weather"}` — specific tool

### Error Handling
```json
{"type": "tool_result", "tool_use_id": "...", "is_error": true,
 "content": "File not found. Available: main.py, utils.py"}
```

## Extended Thinking

```python
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "Analyze this algorithm..."}]
)

for block in response.content:
    if block.type == "thinking":
        print(f"[Thinking] {block.thinking}")
    elif block.type == "text":
        print(f"[Response] {block.text}")
```

`budget_tokens` must be < `max_tokens`. All Claude 4.5/4.6 models support it.

## Sub-Agents

| Type | Model | Tools | Purpose |
|------|-------|-------|---------|
| Explore | Haiku | Read-only | File discovery, code search |
| Plan | Inherited | Read-only | Architecture planning |
| general-purpose | Inherited | All | Complex multi-step tasks |

### Custom Sub-Agent Definition
```markdown
---
name: code-reviewer
description: Reviews code for quality
tools: Read, Glob, Grep
model: sonnet
---
Review code for bugs, security issues, and style violations.
```

Store in `.claude/agents/` or `~/.claude/agents/`.

## Built-in Tool Types

| Type | Purpose |
|------|---------|
| `computer_20250124` | Computer use (screenshot, click, type) |
| `text_editor_20250124` | File editing |
| `bash_20250124` | Shell commands |
| `tool_search_*` | Search over large tool lists (~85% token savings) |
| `code_execution_*` | Programmatic tool calling (~37% savings) |
| `memory_20250818` | Persistent state |

## Sources

- [Agent SDK Python](https://docs.claude.com/en/api/agent-sdk/python)
- [Tool Use Overview](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview)
- [Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)

