Claude Code SDK とは？インストールから Agent 構築まで完全解説

Q: Q. SDK と CLI の両方を使える環境が必要ですか？

はい。Claude Code SDK は内部で Claude Code CLI を呼び出します。そのため `npm install -g @anthropic-ai/claude-code` で CLI を事前にインストールしておく必要があります。

Q: Q. どのモデルが使われますか？

デフォルトは Claude Code CLI の設定に従います。`options` で明示的に指定することも可能です（最新のモデル選択オプションは [Anthropic 公式ドキュメント](https://docs.anthropic.com/en/docs/claude-code/sdk) を参照してください）。

Claude Code を「対話型 CLI ツール」として使うだけでは、その力の半分しか活かせていません。Claude Code SDK を使えば、TypeScript や Python のコードから Claude Code をサブプロセスとして起動し、AI エージェントを完全にプログラム制御できます。本記事では、SDK の仕組みからインストール・実装パターン・マルチエージェント構築まで、公式ドキュメントをもとに実装例付きで解説します。

Claude Code SDK とは何か

Claude Code SDK は、Anthropic が公式に提供する「Claude Code をプログラムから操作するためのライブラリ」 です。

通常の Claude Code はターミナルで人間が対話しながら使いますが、SDK を使うと TypeScript や Python のスクリプトから自動的に起動・制御できます。CI/CD パイプライン、定期バッチ処理、Web アプリケーションのバックエンドなど、「人間が画面の前にいなくても動く自動化」を実現するのが主な用途です。

参考: Anthropic 公式ドキュメント — Claude Code SDK（最新情報は公式サイトで確認してください）

CLI との違いを整理する

比較軸	Claude Code CLI	Claude Code SDK
操作者	人間（対話型）	プログラム（自動）
起動方法	ターミナルで `claude` コマンド	コード内でサブプロセス呼び出し
主な用途	開発作業・コードレビュー	CI/CD・バッチ・自律エージェント
対応言語	—	TypeScript / Python
ストリーミング	ターミナル出力	コールバックで受信

SDK が向いているユースケース

夜間バッチで記事を自動生成 → Cron 起動でコンテンツを量産
PR 作成時に自動コードレビュー → GitHub Actions から SDK を呼び出す
複数エージェントを並列実行 → Orchestrator → Subagent パターンで高速処理
社内チャットボットに Claude Code を組み込む → Node.js サーバーから応答を返す

Claude Code SDK のインストール方法

TypeScript（Node.js）でのインストール

npm install @anthropic-ai/claude-code

Node.js 18 以上が必要です（執筆時点。最新の対応バージョンは Anthropic 公式ドキュメントで確認してください）。

import { query } from "@anthropic-ai/claude-code";

Python でのインストール

pip install claude-code-sdk

Python 3.10 以上が推奨されています（執筆時点。公式ドキュメントで最新要件を確認してください）。

from claude_code_sdk import query, ClaudeCodeOptions

事前準備：Claude Code CLI のインストール

SDK はバックグラウンドで Claude Code CLI を呼び出します。そのため、SDK より先に Claude Code 本体をインストールしておく必要があります。

npm install -g @anthropic-ai/claude-code

Claude Code のインストール手順は Claude Code インストール完全ガイドを参照してください。

TypeScript での基本的な使い方

テキスト生成（シンプルな query）

最もシンプルな使い方は query() 関数にプロンプトを渡すパターンです。

import { query, ResultMessage } from "@anthropic-ai/claude-code";

async function main() {
  const messages: ResultMessage[] = [];

  for await (const message of query({
    prompt: "TypeScript で FizzBuzz を書いてください",
    options: { maxTurns: 1 },
  })) {
    messages.push(message);
  }

  // 最後の assistant メッセージを取得
  const result = messages.at(-1);
  console.log(result?.result);
}

main();

query() は AsyncGenerator を返します。メッセージがストリームで流れてくるため、for await...of で受け取ります。

ストリーミングで逐次出力する

import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Next.js 15 の App Router を解説してください",
  options: {
    maxTurns: 3,
    systemPrompt: "あなたは日本語で回答する技術ライターです。",
  },
})) {
  if (message.type === "assistant") {
    process.stdout.write(message.result ?? "");
  }
}

systemPrompt を渡すことで Claude の振る舞いをカスタマイズできます。CLAUDE.md の代わりにコード内で完結させたい場合に有用です。

会話履歴を維持するマルチターン

import { query, Message } from "@anthropic-ai/claude-code";

let history: Message[] = [];

async function chat(userInput: string) {
  const newHistory: Message[] = [];

  for await (const msg of query({
    prompt: userInput,
    options: {
      conversationHistory: history,
      maxTurns: 1,
    },
  })) {
    newHistory.push(msg);
  }

  // 次のターンのために履歴を更新
  history = [...history, ...newHistory];
  return newHistory.at(-1)?.result;
}

// 複数ターンの会話
await chat("Claude Code の料金を教えて");
await chat("Pro と Max の違いは？");  // 前の文脈を引き継ぐ

Python での基本的な使い方

非同期での query

import anyio
from claude_code_sdk import query, ClaudeCodeOptions

async def main():
    options = ClaudeCodeOptions(max_turns=1)
    
    async with query(
        prompt="Python で CSV を読み込む関数を書いてください",
        options=options,
    ) as stream:
        async for message in stream:
            if message.type == "result":
                print(message.result)

anyio.run(main)

カスタム System Prompt と作業ディレクトリの指定

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path
import anyio

async def review_code():
    options = ClaudeCodeOptions(
        system_prompt="あなたはセキュリティ専門のコードレビュアーです。",
        cwd=Path("/path/to/project"),  # Claude Code が操作するディレクトリ
        max_turns=5,
    )
    
    async with query(
        prompt="このプロジェクトのセキュリティリスクを洗い出してください",
        options=options,
    ) as stream:
        async for message in stream:
            print(message)

anyio.run(review_code)

cwd を指定すると、Claude Code がそのディレクトリのファイルを読み書きできます。

マルチエージェントパターン（Orchestrator / Subagent）

Claude Code SDK の最大の強みは マルチエージェント構成 です。Orchestrator が全体方針を決め、複数の Subagent が並列でタスクをこなす設計は、単一エージェントに比べて処理を高速化できます（タスクの並列化度合いや環境により効果は異なります）。

Orchestrator → Subagent の構成例

import { query } from "@anthropic-ai/claude-code";

// Subagent 定義: それぞれ独立した専門エージェント
async function runSubagent(role: string, task: string) {
  const results: string[] = [];
  for await (const msg of query({
    prompt: task,
    options: {
      systemPrompt: `あなたは${role}の専門家です。与えられたタスクのみに集中してください。`,
      maxTurns: 3,
    },
  })) {
    if (msg.type === "result" && msg.result) {
      results.push(msg.result);
    }
  }
  return results.join("\n");
}

// Orchestrator: 並列で 3 つの Subagent を起動
async function orchestrate(topic: string) {
  const [research, outline, references] = await Promise.all([
    runSubagent("リサーチャー", `「${topic}」について最新情報を調査してください`),
    runSubagent("ライター", `「${topic}」の記事構成案を 5 見出しで作成してください`),
    runSubagent("SEO アナリスト", `「${topic}」に関連する検索キーワードを 10 個列挙してください`),
  ]);

  // Orchestrator が最終統合
  for await (const msg of query({
    prompt: `以下の情報を統合して、記事の初稿を日本語で書いてください:\n\nリサーチ:\n${research}\n\n構成:\n${outline}\n\n関連KW:\n${references}`,
    options: { maxTurns: 5 },
  })) {
    if (msg.type === "result") {
      console.log(msg.result);
    }
  }
}

orchestrate("Claude Code SDK の使い方");

このパターンは Claude Code Skills × Subagents × Hooks 使い分け完全マップで詳しく解説しています。

パーミッション制御（セキュリティ設計）

本番環境でエージェントを動かす際は、許可するツールを明示的に制限することが重要です。

import { query } from "@anthropic-ai/claude-code";

for await (const msg of query({
  prompt: "package.json の依存関係を最新化してください",
  options: {
    allowedTools: ["Read", "Edit", "Bash(npm install*)"],  // 許可するツールのみ指定
    maxTurns: 10,
  },
})) {
  console.log(msg);
}

allowedTools で許可するツールを絞ることで、想定外のファイル削除や外部 API 呼び出しを防げます。Hooks との組み合わせについては Claude Code Hooks 完全ガイドを参照してください。

Claude Code SDK の料金

SDK の利用料金は、バックエンドで Claude Code CLI が何を使うかによって決まります。

実行形態	料金形態	注意点
Pro / Max サブスクリプション	月額固定（$20 / $200）	個人アカウントへの紐付けが必要
API キー（Anthropic Direct）	トークン従量課金	自動化・CI/CD での本番運用に適合
AWS Bedrock / Google Vertex	クラウド従量課金	エンタープライズ・コンプライアンス重視の場合

自動化バッチや CI/CD に SDK を使う場合、API キーでの従量課金が最も管理しやすい です。料金プランの詳細は Claude Code 料金完全ガイドで比較しています。

⚠️ 本番環境に API キーを埋め込む際は必ず環境変数（.env）で管理し、コードにハードコードしないよう徹底してください（セキュリティルール: 参考 Anthropic API キー管理ガイドライン）。

よくある質問

Q. SDK と CLI の両方を使える環境が必要ですか？

はい。Claude Code SDK は内部で Claude Code CLI を呼び出します。そのため npm install -g @anthropic-ai/claude-code で CLI を事前にインストールしておく必要があります。

Q. どのモデルが使われますか？

デフォルトは Claude Code CLI の設定に従います。options で明示的に指定することも可能です（最新のモデル選択オプションは Anthropic 公式ドキュメントを参照してください）。

Q. GitHub Actions から使えますか？

使えます。API キーを GitHub Secrets に登録し、環境変数として渡すパターンが標準的です。ただし、Claude Code CLI が Node.js 環境を必要とするため、Actions の runs-on: ubuntu-latest に Node.js をセットアップするステップを追加してください。

Q. サブエージェントの並列数に上限はありますか？

Anthropic の利用規約上の同時接続制限と、ご利用のプラン・APIの Rate Limit が上限になります。Promise.all() で複数を並列実行できますが、Rate Limit エラーが発生した場合はリトライロジックを実装することを推奨します（詳細は Anthropic Rate Limits ガイドを参照）。

まとめ：Claude Code SDK で自動化の次のステージへ

Claude Code SDK を使うことで、対話型の AI アシスタントから プログラム制御可能な自律エージェント基盤 へのステップアップが実現します。

単発タスク: query() で最小コード量から始める
業務自動化: systemPrompt + cwd で専門化エージェントを構築
スケール化: Orchestrator / Subagent パターンで並列処理

まずはローカルの小さなスクリプトから試して、動作を確認してみてください。Claude Code の全体像は Claude Code 完全ガイドから把握できます。

Claude Code Superpowers × Agent Skills 完全ガイド — SDK と Skills を組み合わせたエージェント構築パターン
Claude Code サブエージェントおすすめ 8 選 — 業務別サブエージェント設計の実践レシピ
Claude Code × GitHub 完全ガイド — SDK + CI/CD で PR 自動化を実装
Claude Code 完全ガイド — 料金・Skills・MCP・Hooks を網羅したピラー記事

この記事の著者

claude-code-media 編集部／ Claude Code 専門編集チーム

Claude Code の非エンジニア向け業務効率化メディア『claude-code-lab.jp』を運営。フリーランス・中小企業・個人開発者向けに、実装テンプレ・業務自動化テクニック・Vibe Coding 入門を配信。

Claude Code 完全ガイドVibe CodingAI 業務効率化非エンジニア向け AI 教育MCP（Model Context Protocol）

運営: 株式会社AIKNOW著者プロフィールを見る →無料ニュースレターを購読 →

この記事の続きを、完全マニュアルで体系的に。