# Claude Agent SDK 入門

Claude Agent SDK は、Claude モデルに基づいた AI Agent アプリケーションを構築するための Anthropic 公式開発キットです。Claude Code（CLI ツール）とは異なり、SDK は開発者を対象としており、Claude の能力を自分のアプリケーションに統合できます。

## Claude Agent SDK とは？

Claude Agent SDK は、以下を作成できるアプリケーションを構築するためのビルディングブロックを提供します：

- **自然言語の指示を理解**し、複雑なタスクを実行
- **ツールを使用**（検索、コード実行、ファイル操作など）
- **マルチターン対話**のコンテキストを維持
- **外部サービスに接続**（MCP サーバー経由）

## SDK のインストール

### Python SDK

```bash
pip install anthropic
```

### TypeScript SDK

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

## クイックスタート

### 基本的なメッセージ呼び出し

```python
from anthropic import Anthropic

# QCode.cc API 経由
client = Anthropic(
    base_url="https://api.qcode.cc/api",
    api_key="cr_your_api_key"
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "RESTful API について説明してください"}
    ]
)

print(message.content[0].text)
```

### ストリーミング応答

```python
with client.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Python のクイックソート関数を書いてください"}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

## ツールの使用（Tool Use）

Tool Use は Agent のコア機能で、モデルが外部ツールを呼び出すことを可能にします。

### ツールの定義

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.qcode.cc/api",
    api_key="cr_your_api_key"
)

# 検索ツールを定義
tools = [
    {
        "name": "search_web",
        "description": "ウェブで検索して情報を取得",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "検索キーワード"
                }
            },
            "required": ["query"]
        }
    }
]

# ツール付きでメッセージを送信
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "(15 + 25) * 2 を計算してください"}
    ],
    tools=tools
)

# ツール呼び出しを処理
for content in message.content:
    if content.type == "text":
        print(content.text)
    elif content.type == "tool_use":
        print(f"ツール呼び出し: {content.name}")
        print(f"引数: {content.input}")

        # ツールの実行をシミュレート
        if content.name == "calculate":
            result = eval(content.input["expression"])
            tool_result = str(result)
        elif content.name == "search_web":
            tool_result = f"検索結果 '{content.input['query']}' ..."

        # 結果をモデルに返す
        message = client.messages.create(
            model="claude-opus-5",
            max_tokens=4096,
            messages=[
                {"role": "user", "content": "(15 + 25) * 2 を計算してください"},
                message,
                {
                    "role": "user",
                    "content": None,
                    "type": "tool_result",
                    "tool_use_id": content.id,
                    "content": tool_result
                }
            ],
            tools=tools
        )
```

## ストリーミングでのツール呼び出し

```python
with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Create a file named hello.py that prints 'Hello, World!'"}
    ],
    tools=[
        {
            "name": "write_file",
            "description": "Write content to a file",
            "input_schema": {
                "type": "object",
                "properties": {
                    "filename": {"type": "string"},
                    "content": {"type": "string"}
                },
                "required": ["filename", "content"]
            }
        }
    ]
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)
            elif event.delta.type == "tool_use_delta":
                print(f"\n[Tool Call] {event.delta.name}")
```

## Prompt Caching

Prompt Caching は長い会話のコストを大きく下げられます：

```python
# システムプロンプト（キャッシュされる）
system_prompt = """You are a professional code review assistant.
Your responsibilities:
1. Check code security
2. Identify performance issues
3. Verify code standards
4. Provide improvement suggestions
"""

# cache_control でキャッシュ対象を指定する
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Review @src/auth/login.ts"}
    ]
)
```

## Agent の構築例

```python
from anthropic import Anthropic
from typing import List

class CodeReviewAgent:
    def __init__(self, api_key: str):
        self.client = Anthropic(
            base_url="https://api.qcode.cc/api",
            api_key=api_key
        )
        self.system_prompt = """You are a professional code review assistant.
Focus on: security, performance, readability, best practices.
Output for each review: issue list, severity, fix suggestions."""

    def review(self, code_snippet: str) -> str:
        message = self.client.messages.create(
            model="claude-opus-5",
            max_tokens=4096,
            system=self.system_prompt,
            messages=[
                {"role": "user", "content": f"Review this code:\n\n{code_snippet}"}
            ]
        )
        return message.content[0].text

# Usage
agent = CodeReviewAgent("cr_your_api_key")
result = agent.review("SELECT * FROM users WHERE id = " + user_id)
```

## Claude Code との違い

| 項目 | Claude Agent SDK | Claude Code |
|---------|------------------|-------------|
| 対象ユーザー | 開発者 | 個人の開発者 |
| 実行場所 | あなたのアプリケーション | コマンドライン |
| ファイル操作 | 自分で実装する | 内蔵 |
| ターミナルコマンド | 自分で実装する | 内蔵 |
| Git 連携 | 自分で実装する | 内蔵 |
| 用途 | AI アプリを作る | プログラミングの支援 |

## QCode.cc 設定

```python
import os

# 方法 1: 環境変数
os.environ["ANTHROPIC_BASE_URL"] = "https://api.qcode.cc/api"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "cr_your_key"

client = Anthropic()  # 環境変数を自動読み取り

# 方法 2: アジアノード（中国大陸推奨）
client = Anthropic(
    base_url="https://api.qcode.cc/api",
    api_key="cr_your_key"
)
```

## 次のステップ

- [API リファレンス](/docs/getting-started/endpoints-and-api-paths) - 完全な API パラメータ説明
- [モデル選択ガイド](/docs/usage/model-selection) - 適切なモデルの