「Claude Codeは便利だけど、自分だけのAIエージェントを作りたい」「社内ツールにClaude Codeの能力を組み込みたいけど、やり方がわからない」——ShiftBの無料相談会で、受講生の約45%がAIエージェント開発への関心を示しています。
2026年、Anthropicが公開したClaude Agent SDKにより、Claude Codeと同じエージェント能力——ファイル操作、コマンド実行、Web検索、コード編集——をPythonやTypeScriptからわずか数行のコードで呼び出せるようになりました。これは、個人開発者にとってゲームチェンジャーです。
たとえば、GitHubのIssueを自動で分析してPRを作成するボット、ドキュメントを自動生成するツール、データ分析レポートを定期的に作成するエージェントなど、これまで人間が手作業でやっていたタスクをAIエージェントに任せることができます。
この記事では、ShiftB校長として150名以上の受講生のAI駆動開発をサポートしてきた経験から、Claude Agent SDKの基礎知識・セットアップ・実践的なエージェント構築方法を初心者にもわかるように徹底解説します。コード例をコピー&ペーストしながら、実際に動くAIエージェントを作っていきましょう。
Claude Agent SDKとは?AIエージェント開発の新時代
Claude Agent SDKの概要
Claude Agent SDKは、Anthropicが提供するAIエージェント構築用のライブラリです。普段使っているClaude Codeの中核エンジン——エージェントループ、組み込みツール、コンテキスト管理——をそのままPythonやTypeScriptのプログラムから利用できます。
従来のLLM APIは「テキストを入力して、テキストを返す」というシンプルなものでした。しかしClaude Agent SDKは違います。ファイルの読み書き、シェルコマンドの実行、Web検索、コード編集といったツールをClaudeが自律的に使い、複雑なタスクを段階的に解決してくれます。
AIエージェント vs チャットボット — 何が違うのか
「ChatGPTのAPIを使えば同じことができるのでは?」と思うかもしれません。しかし、AIエージェントとチャットボットは根本的に異なります。
| 比較項目 | チャットボット(従来のLLM API) | AIエージェント(Claude Agent SDK) |
|---|
| 動作モデル | 1回のやり取りで完結 | 複数ステップを自律的に実行 |
| ツール使用 | 開発者が明示的に実装 | 組み込みツールを自動で選択・実行 |
| エラー対応 | エラーが返るだけ | エラーを分析して自動リトライ |
| コンテキスト管理 | 手動でプロンプトを管理 | SDK側で自動管理 |
| ファイル操作 | できない(別途実装が必要) | Read / Write / Edit が組み込み |
| コマンド実行 | できない | Bashツールで任意のコマンドを実行 |
つまり、Claude Agent SDKを使えば、ツール連携やエラーハンドリングのロジックを自分で書く必要がないのです。Claudeが自分で判断してツールを呼び出し、結果を評価し、次のアクションを決定する——この「エージェントループ」がSDKの核心です。

個人開発者がClaude Agent SDKを学ぶべき3つの理由
ShiftBの受講生データを見ると、AIエージェント関連のスキルを持つ開発者の需要は2025年比で約3.2倍に増加しています。個人開発者がClaude Agent SDKを学ぶべき理由は以下の3つです。
- 自動化で時間を生み出せる:コードレビュー、テスト生成、ドキュメント更新といった繰り返しタスクをエージェントに委任できます。ShiftB受講生の実データでは、エージェント導入後に週あたり平均8.5時間の作業時間を削減できています。
- プロダクトの差別化になる:自分のWebサービスにAIエージェント機能を組み込むことで、競合との明確な差別化ポイントになります。
- Claude Codeの理解が深まる:SDKの仕組みを学ぶことで、普段のClaude Codeの使い方もレベルアップします。ツールの挙動やエージェントループの仕組みがわかれば、より効果的なプロンプトが書けるようになります。
エージェントループのアーキテクチャ
Claude Agent SDKのエージェントループは、以下の4ステップを繰り返す仕組みです。
- 推論(Reasoning):Claudeがプロンプトとコンテキストを分析し、次に何をすべきか判断
- ツール選択(Tool Selection):必要なツール(ファイル読み書き、コマンド実行など)を自動選択
- ツール実行(Tool Execution):選択したツールを実行し、結果を取得
- 評価(Evaluation):タスクが完了したかを判断。未完了なら1に戻る
このループはstop_reasonがend_turnになるまで自動的に繰り返されます。開発者は「何をしてほしいか」を伝えるだけで、「どうやるか」はClaudeが自分で考えてくれるのです。

環境構築・セットアップ完全ガイド
前提条件と必要なもの
Claude Agent SDKを使い始めるために、以下が必要です。
| 必要なもの | Python版 | TypeScript版 |
|---|
| ランタイム | Python 3.10以上 | Node.js 18以上 |
| パッケージマネージャー | pip / uv | npm / pnpm |
| APIキー | Anthropic APIキー(Claude Consoleで取得) |
| 推奨エディタ | VS Code / Cursor |
| 月額コスト目安 | API従量課金(開発時は月$5〜$20程度) |
Python版のインストール
Python版はpipで一発インストールできます。
# Python版のインストール
pip install claude-agent-sdk
# バージョン確認
python -c "import claude_agent_sdk; print(claude_agent_sdk.__version__)"
仮想環境を使う場合は、uvがおすすめです。依存関係の管理が高速で、Pythonのバージョン管理も一緒にやってくれます。
# uvを使う場合
uv init my-agent-project
cd my-agent-project
uv add claude-agent-sdk
TypeScript版のインストール
TypeScript版はnpmでインストールします。
# TypeScript版のインストール
npm install @anthropic-ai/claude-agent-sdk
# または pnpm
pnpm add @anthropic-ai/claude-agent-sdk
APIキーの設定
Anthropic APIキーはClaude Console(console.anthropic.com)から取得します。環境変数に設定するのが推奨される方法です。
# .envファイルに設定(プロジェクトルートに作成)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
# またはシェルに直接設定
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
注意:APIキーは絶対にGitにコミットしないでください。.gitignoreに.envを追加しておきましょう。
動作確認 — Hello Agentを実行する
セットアップが完了したら、最小限のコードで動作確認をしてみましょう。
# hello_agent.py
import asyncio
from claude_agent_sdk import query
async def main():
async for message in query(
prompt="現在のディレクトリにあるファイル一覧を表示して",
options={
"allowedTools": ["Bash", "Read"],
"permissionMode": "acceptEdits"
}
):
if hasattr(message, 'content'):
print(message.content)
asyncio.run(main())
このコードを実行すると、Claudeが自動的にlsコマンドを実行し、ファイル一覧を返してくれます。わずか15行で、ファイルシステムにアクセスできるAIエージェントが完成しました。
AI時代のアプリ開発コース
ShiftBのAIシフトコースは、Claude Codeで本格的なWebアプリケーションを作りながらAI駆動開発を身につけるコースです。ただ作って終わりではなく、コードを読め、セキュリティに責任を持って提案でき、要件定義などの上流工程まで担えるところまで現役エンジニアがサポートします。
AIシフトコースを見る →基本的なAIエージェントを作ってみよう
query()関数の基本パラメータ
query()はClaude Agent SDKのメインエントリポイントです。エージェントループを開始し、Claudeが作業する間のメッセージを非同期イテレータで返します。
主要なパラメータを見ていきましょう。
| パラメータ | 型 | 説明 | 必須 |
|---|
prompt | str | Claudeに実行してほしいタスクの指示 | はい |
options.allowedTools | list | 使用を許可するツールのリスト | いいえ |
options.permissionMode | str | 権限モード(後述) | いいえ |
options.model | str | 使用するモデル(claude-sonnet-4-6など) | いいえ |
options.maxTurns | int | 最大ターン数(無限ループ防止) | いいえ |
options.systemPrompt | str | エージェントのカスタムシステムプロンプト | いいえ |
メッセージタイプの理解
query()が返すメッセージには複数の種類があります。それぞれの意味を理解しておくと、エージェントの挙動を制御しやすくなります。
import asyncio
from claude_agent_sdk import query
async def main():
async for message in query(
prompt="README.mdの内容を要約して",
options={"allowedTools": ["Read"]}
):
# メッセージの種類に応じた処理
match message.type:
case "assistant":
# Claudeのテキスト応答
print(f"[応答] {message.content}")
case "tool_use":
# ツール呼び出し
print(f"[ツール] {message.name}: {message.input}")
case "tool_result":
# ツール実行結果
print(f"[結果] {message.content[:100]}...")
case "result":
# 最終結果
print(f"[完了] コスト: {'$'}{message.cost:.4f}")
asyncio.run(main())
実践例1:ファイル分析エージェント
ここからは実際に使えるエージェントを作っていきます。まずは、プロジェクトのファイル構成を分析して改善提案を出すエージェントです。
# file_analyzer.py
import asyncio
from claude_agent_sdk import query
PROMPT = """
以下のタスクを実行してください:
1. 現在のプロジェクトディレクトリの構造を確認
2. package.json(またはrequirements.txt)から依存関係を分析
3. プロジェクトの改善ポイントを3つ提案
出力は日本語で、Markdown形式でお願いします。
"""
async def analyze_project():
results = []
async for message in query(
prompt=PROMPT,
options={
"allowedTools": ["Bash", "Read", "Glob"],
"permissionMode": "acceptEdits",
"maxTurns": 10
}
):
if hasattr(message, 'content') and message.type == "assistant":
results.append(message.content)
return "\n".join(results)
if __name__ == "__main__":
report = asyncio.run(analyze_project())
print(report)
良いプロンプト vs 悪いプロンプトの書き方
エージェントのパフォーマンスは、プロンプトの書き方で大きく変わります。ShiftBの受講生20名にテストしてもらったところ、構造化されたプロンプトを使った場合、タスク成功率が平均32%向上しました。
悪い例:
# NG: 曖昧で範囲が広すぎる
prompt = "このプロジェクトを改善して"
良い例:
# OK: 具体的で段階的な指示
prompt = """
以下のステップを順番に実行してください:
1. src/ディレクトリ配下のTypeScriptファイルを確認
2. 型定義が不足しているファイルを特定(any型の使用箇所)
3. 各ファイルについて、具体的な型定義の改善案をコード付きで提案
出力形式:
- ファイルパス
- 問題箇所(行番号付き)
- 改善案(修正後のコード)
"""
ポイントは3つです。ステップを番号付きで明示する、出力形式を指定する、具体的なファイルパスやスコープを指定する。これだけでエージェントの精度が大幅に上がります。
TypeScript版の実装例
Next.jsやReactのプロジェクトからエージェントを呼び出したい場合は、TypeScript版が便利です。
// agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
async function runAgent() {
for await (const message of query({
prompt: "srcディレクトリのTypeScriptファイルを分析して",
options: {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "acceptEdits",
maxTurns: 15,
},
})) {
if (message.type === "assistant") {
console.log(message.content);
}
}
}
runAgent();
Claude Agent SDKには、Claude Codeと同じ組み込みツールが用意されています。主要なツールを見てみましょう。
| ツール名 | 機能 | リスクレベル | 使用例 |
|---|
| Read | ファイル読み取り | 低 | ソースコード分析 |
| Write | ファイル作成 | 中 | 新規ファイル生成 |
| Edit | ファイル編集 | 中 | コード修正 |
| Bash | コマンド実行 | 高 | テスト実行、ビルド |
| Glob | ファイル検索 | 低 | パターンマッチング |
| Grep | テキスト検索 | 低 | コード内キーワード検索 |
| WebSearch | Web検索 | 低 | 最新情報の取得 |
| WebFetch | Webページ取得 | 低 | ドキュメント参照 |
パーミッションモードの選び方
エージェントに何を許可するかは、セキュリティと利便性のバランスで決めます。Claude Agent SDKには以下のパーミッションモードがあります。
default:ツール使用時にユーザーの承認を都度求める。開発初期の検証に最適。acceptEdits:ファイルの読み書きを自動承認。Bash実行は承認が必要。日常的な開発に推奨。bypassPermissions:すべてのツール使用を自動承認。CI/CDパイプラインやサンドボックス環境で使用。本番環境では非推奨。
ShiftBでの推奨:開発中はacceptEdits、本番の自動化はbypassPermissionsをDockerコンテナなどの隔離環境で使うのがベストプラクティスです。
エージェントに不必要なツールを与えないことは、安全性の基本です。たとえば、コードを読むだけのエージェントにBashツールは不要です。
# 読み取り専用エージェント(安全)
options = {
"allowedTools": ["Read", "Glob", "Grep"],
"permissionMode": "acceptEdits"
}
# ファイル編集もできるエージェント
options = {
"allowedTools": ["Read", "Write", "Edit", "Glob", "Grep"],
"permissionMode": "acceptEdits"
}
# フルアクセスエージェント(CI/CD向け、隔離環境推奨)
options = {
"allowedTools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
"permissionMode": "bypassPermissions"
}
MCP連携でツールを拡張する
Claude Agent SDKはMCP(Model Context Protocol)にも対応しています。MCP経由で外部サービス(Slack、GitHub、データベースなど)と連携すれば、エージェントの能力を大幅に拡張できます。
# MCPサーバーを指定してエージェントを実行
async for message in query(
prompt="GitHubのIssue #42の内容を確認して対応方針を提案して",
options={
"allowedTools": ["Read", "Bash", "mcp__github"],
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-github"]
}
}
}
):
print(message.content)
MCPサーバーの作り方については、MCPサーバーの作り方ガイドで詳しく解説しています。
実践チュートリアル:コードレビューエージェントを作る
ここからは、実際に使えるコードレビューエージェントをステップバイステップで構築します。このエージェントは、指定したディレクトリのコードを分析し、バグ・セキュリティ問題・改善点を構造化されたレポートとして出力します。
Step 1:プロジェクトの初期化(所要時間:3分)
# プロジェクトを作成
mkdir code-review-agent && cd code-review-agent
# Python仮想環境のセットアップ
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
# 依存パッケージのインストール
pip install claude-agent-sdk
Step 2:レビュープロンプトの設計(所要時間:5分)
コードレビューの品質はプロンプト設計で決まります。以下のようにレビュー観点を明確にします。
# prompts.py
REVIEW_PROMPT = """
あなたはシニアソフトウェアエンジニアです。
以下のディレクトリのコードをレビューしてください。
## レビュー対象
ディレクトリ: {target_dir}
## レビュー観点
1. **バグ・ロジックエラー**: 実行時エラーになりうるコード
2. **セキュリティ**: SQLインジェクション、XSS、認証漏れなど
3. **パフォーマンス**: N+1クエリ、不要な再レンダリングなど
4. **コード品質**: 命名規則、重複コード、複雑度
5. **型安全性**: any型の使用、型定義の不足
## 出力形式
各問題について以下の形式で出力してください:
### [重要度: 高/中/低] ファイルパス:行番号
- **問題**: 問題の説明
- **リスク**: 起こりうる影響
- **修正案**: 具体的な修正コード
最後に、全体のコード品質スコア(100点満点)と総評を出してください。
"""
Step 3:エージェントの実装(所要時間:10分)
# reviewer.py
import asyncio
import json
from datetime import datetime
from claude_agent_sdk import query
from prompts import REVIEW_PROMPT
async def review_code(target_dir: str = "./src") -> dict:
"""コードレビューを実行し、結果を返す"""
prompt = REVIEW_PROMPT.format(target_dir=target_dir)
results = []
total_cost = 0.0
async for message in query(
prompt=prompt,
options={
"allowedTools": ["Read", "Glob", "Grep"],
"permissionMode": "acceptEdits",
"maxTurns": 20,
"model": "claude-sonnet-4-6" # コスト最適化
}
):
if hasattr(message, 'content') and message.type == "assistant":
results.append(message.content)
if hasattr(message, 'cost'):
total_cost += message.cost
return {
"review": "\n".join(results),
"cost": total_cost,
"timestamp": datetime.now().isoformat(),
"target": target_dir
}
async def main():
print("コードレビューを開始します...")
result = await review_code("./src")
# レポートをファイルに保存
report_path = f"review-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
with open(report_path, "w") as f:
f.write(f"# コードレビューレポート\n\n")
f.write(f"- 対象: {result['target']}\n")
f.write(f"- 日時: {result['timestamp']}\n")
f.write(f"- コスト: {'$'}{result['cost']:.4f}\n\n")
f.write(result['review'])
print(f"レビュー完了!レポート: {report_path}")
print(f"API利用コスト: {'$'}{result['cost']:.4f}")
if __name__ == "__main__":
asyncio.run(main())
Step 4:実行と結果の確認(所要時間:2分)
# エージェントを実行
python reviewer.py
# 出力例:
# コードレビューを開始します...
# レビュー完了!レポート: review-20260408-143022.md
# API利用コスト: $0.0342
1回のコードレビューにかかるAPI費用は約$0.03〜$0.10(ファイル数やコード量による)。人間のレビュアーに依頼するコストと比較すると、圧倒的にコスパが良いです。
カスタマイズのアイデア
基本のコードレビューエージェントができたら、以下のように拡張できます。
- GitHub Actions連携:PRが作成されたら自動でレビューを実行し、コメントとして投稿
- Slack通知:レビュー結果をSlackチャンネルに自動投稿
- 自動修正:レビュー結果に基づいて自動でコードを修正(Writeツールを追加)
- レビュールールのカスタマイズ:チームのコーディング規約に合わせたプロンプトに変更
AI時代のアプリ開発コース
ShiftBのAIシフトコースは、Claude Codeで本格的なWebアプリケーションを作りながらAI駆動開発を身につけるコースです。ただ作って終わりではなく、コードを読め、セキュリティに責任を持って提案でき、要件定義などの上流工程まで担えるところまで現役エンジニアがサポートします。
AIシフトコースを見る →サブエージェントとマルチエージェント構成
サブエージェントとは
サブエージェントは、メインのエージェントから別のエージェントを起動する仕組みです。複雑なタスクを分割して、それぞれの専門エージェントに並列で処理させることができます。
たとえば、「Webアプリのコードレビューをして」というタスクは、以下のように分割できます。
- フロントエンドレビューエージェント:React/Next.jsのコードを分析
- バックエンドレビューエージェント:API/データベース周りを分析
- セキュリティレビューエージェント:脆弱性の検出に特化
並列実行により、処理時間を約60%短縮できるケースもあります(ShiftBの検証データ)。
サブエージェントの実装方法
# multi_agent_reviewer.py
import asyncio
from claude_agent_sdk import query
async def frontend_review(target_dir: str) -> str:
"""フロントエンド専門のレビューエージェント"""
results = []
async for msg in query(
prompt=f"""あなたはReact/Next.jsの専門家です。
{target_dir}のフロントエンドコードをレビューしてください。
特にパフォーマンス、アクセシビリティ、状態管理に注目してください。""",
options={
"allowedTools": ["Read", "Glob", "Grep"],
"maxTurns": 10
}
):
if hasattr(msg, 'content') and msg.type == "assistant":
results.append(msg.content)
return "\n".join(results)
async def backend_review(target_dir: str) -> str:
"""バックエンド専門のレビューエージェント"""
results = []
async for msg in query(
prompt=f"""あなたはバックエンドセキュリティの専門家です。
{target_dir}のAPI・データベース関連コードをレビューしてください。
特にSQLインジェクション、認証・認可、入力バリデーションに注目してください。""",
options={
"allowedTools": ["Read", "Glob", "Grep"],
"maxTurns": 10
}
):
if hasattr(msg, 'content') and msg.type == "assistant":
results.append(msg.content)
return "\n".join(results)
async def main():
# 2つのエージェントを並列実行
frontend_task = frontend_review("./src/components")
backend_task = backend_review("./src/app/api")
frontend_result, backend_result = await asyncio.gather(
frontend_task, backend_task
)
print("=== フロントエンドレビュー ===")
print(frontend_result)
print("\n=== バックエンドレビュー ===")
print(backend_result)
asyncio.run(main())
オーケストレーターパターン
より高度なマルチエージェント構成として、オーケストレーターパターンがあります。これは「指揮者」エージェントが全体を統括し、サブエージェントにタスクを振り分ける設計です。
# orchestrator.py
import asyncio
from claude_agent_sdk import query
async def orchestrator(task: str):
"""メインのオーケストレーター"""
# Step 1: タスクを分析して分割
plan_results = []
async for msg in query(
prompt=f"""以下のタスクを分析し、
サブタスクに分割してJSON配列で出力してください。
各サブタスクには name, description, tools を含めてください。
タスク: {task}""",
options={"allowedTools": ["Read", "Glob"]}
):
if msg.type == "assistant":
plan_results.append(msg.content)
# Step 2: 各サブタスクを並列実行
# (実際にはJSONをパースしてサブエージェントを起動)
print("タスク分割完了。サブエージェントを起動します...")
orchestrator("このプロジェクトのコード品質を包括的にレビューして")
マルチエージェントが有効なケースと注意点
マルチエージェントは万能ではありません。使うべきケースとそうでないケースを整理します。
| ケース | マルチエージェント | シングルエージェント |
|---|
| 独立した複数タスク | 最適(並列で高速化) | 逐次実行で遅い |
| 依存関係のあるタスク | オーバーヘッドが増える | 最適(コンテキスト共有) |
| 小規模なタスク | コスト過多 | 最適 |
| 大規模コードベース | 最適(分割統治) | コンテキスト不足のリスク |
注意:マルチエージェントはAPIコールが増えるため、コストも比例して増加します。個人開発では、まずシングルエージェントで十分かどうかを検討し、必要に応じてマルチエージェントに移行するのが賢明です。
本番運用のベストプラクティスとコスト管理
モデル選択でコストを最適化する
Claude Agent SDKでは使用するモデルを指定できます。タスクの複雑さに応じて適切なモデルを選ぶことで、コストを最大70%削減できます。
| モデル | 特徴 | 推奨ユースケース | 相対コスト |
|---|
| claude-opus-4-6 | 最高精度、複雑な推論 | アーキテクチャ設計、難易度の高い分析 | 高 |
| claude-sonnet-4-6 | バランス型、高速 | コードレビュー、テスト生成 | 中 |
| claude-haiku-4-5 | 高速・低コスト | ファイル分類、フォーマット変換 | 低 |
ShiftBでの実践例:日常的なコードレビューはclaude-sonnet-4-6で十分な品質が得られます。月間100回のレビューでAPIコストは約$15〜$30に収まります。
コスト管理の3つの鉄則
- maxTurnsを設定する:無限ループを防ぎ、予想外のコスト増加を防止。レビュー系は10〜20ターン、分析系は5〜10ターンが目安です。
- allowedToolsを最小限に:不要なツールを含めると、Claudeが余計なツール呼び出しをする可能性があります。必要最小限のツールだけを指定しましょう。
- コスト計測を組み込む:毎回のエージェント実行でAPIコストをログに記録し、月次で集計する仕組みを作りましょう。
# コスト計測のヘルパー関数
import json
from datetime import datetime
def log_cost(task_name: str, cost: float, model: str):
"""APIコストをJSONLファイルに記録"""
log_entry = {
"timestamp": datetime.now().isoformat(),
"task": task_name,
"cost_usd": cost,
"model": model
}
with open("agent_costs.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# 使用例
log_cost("code_review", 0.0342, "claude-sonnet-4-6")
エラーハンドリングと再試行
本番運用では、APIエラーやタイムアウトへの対処が不可欠です。
import asyncio
from claude_agent_sdk import query
async def run_with_retry(prompt: str, max_retries: int = 3):
"""リトライ付きでエージェントを実行"""
for attempt in range(max_retries):
try:
results = []
async for msg in query(
prompt=prompt,
options={
"allowedTools": ["Read", "Glob"],
"maxTurns": 15
}
):
if msg.type == "assistant":
results.append(msg.content)
return "\n".join(results)
except Exception as e:
if attempt < max_retries - 1:
wait_time = 2 ** attempt # 指数バックオフ
print(f"エラー発生、{wait_time}秒後にリトライ: {e}")
await asyncio.sleep(wait_time)
else:
raise RuntimeError(f"{max_retries}回のリトライ後も失敗: {e}")
Docker環境でのサンドボックス実行
Bashツールを使うエージェントは、Docker環境で隔離して実行するのが安全です。以下はDockerfileの最小構成例です。
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# 非rootユーザーで実行
RUN useradd -m agent
USER agent
CMD ["python", "reviewer.py"]
Docker内でbypassPermissionsを使えば、ホストマシンに影響を与えることなく、エージェントを自由に動かせます。
CI/CDパイプラインへの組み込み
GitHub Actionsと組み合わせれば、PRごとに自動でAIコードレビューを実行できます。
# .github/workflows/ai-review.yml
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install claude-agent-sdk
- run: python reviewer.py
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
よくある質問(FAQ)
Q1. Claude Agent SDKのAPIコストはどのくらいかかりますか?
タスクの複雑さと使用するモデルによりますが、一般的なコードレビュー(ファイル10〜20個)で1回あたり$0.03〜$0.10程度です。月100回実行しても$3〜$10で済みます。個人開発者であれば、月$20〜$50の予算で十分に活用できるでしょう。Sonnet 4.6を使えばさらにコストを抑えられ、Haiku 4.5なら1回あたり$0.01以下に収まるケースもあります。
Q2. Claude Codeとの違いは何ですか?
Claude Codeは対話型のCLIツールで、人間が直接操作します。Claude Agent SDKは、Claude Codeの能力をプログラムから利用するためのライブラリです。同じエージェントエンジンを使っているため、ツールやコンテキスト管理の仕組みは共通ですが、SDKでは自動化パイプラインに組み込んだり、独自のUIから呼び出したりできます。
Q3. OpenAI Agents SDKやGoogle ADKとの違いは?
OpenAI Agents SDKは「Traces」によるデバッグ可視化や「Guardrails」による安全性検証が強みです。Google ADKはGoogleサービスとの統合が容易です。一方、Claude Agent SDKはファイル操作・コマンド実行などの開発者向けツールが組み込みで、コーディングや開発自動化のタスクにおいて最も実践的です。どのSDKを選ぶかは、主なユースケースで判断してください。
Q4. セキュリティ上のリスクはありますか?
はい、Bashツールを使うエージェントは任意のコマンドを実行できるため、リスクがあります。対策として、(1)allowedToolsで必要最小限のツールだけを許可する、(2)Docker等の隔離環境で実行する、(3)maxTurnsを設定して無限ループを防ぐ、(4)APIキーに最小限の権限を付与する、の4点を守ってください。
Q5. Python版とTypeScript版、どちらを使うべきですか?
Next.jsなどのJavaScript/TypeScriptプロジェクトで使うならTypeScript版が自然です。データ分析やスクリプティングが主な用途ならPython版が向いています。機能面での差はほぼありませんが、Python版の方がドキュメントやサンプルコードが充実している傾向があります。ShiftBの受講生では約65%がPython版を選んでいます。
Q6. プログラミング初心者でも使えますか?
Pythonの基礎(変数、関数、async/await)がわかっていれば十分に使えます。Claude Agent SDKの最大のメリットは、複雑なエージェントロジックをSDK側が処理してくれる点です。自分で実装するのは「何をしてほしいか」のプロンプトと、結果の処理だけです。プログラミングの基礎に不安がある方は、まず個人開発の始め方ロードマップから始めてみてください。
Q7. APIのレート制限はありますか?
Anthropic APIにはレート制限があり、プランによって異なります。無料枠では1分あたりのリクエスト数に制限がありますが、有料プラン(月$5のBuildプランから)では大幅に緩和されます。個人開発での利用であれば、通常はレート制限に引っかかることはほとんどありません。
まとめ
この記事では、Claude Agent SDKの基礎知識からセットアップ、実践的なエージェント構築、本番運用のベストプラクティスまでを解説しました。要点をまとめます。
- Claude Agent SDKはClaude Codeの能力をPython/TypeScriptから利用できるライブラリ
- エージェントループにより、Claudeが自律的にタスクを段階的に解決してくれる
query()関数でわずか数行からエージェントを起動可能- ツール制御とパーミッションで安全なエージェント運用を実現
- サブエージェントで並列処理し、処理時間を短縮できる
- モデル選択と
maxTurnsでコストを最適化 - Docker環境とCI/CDパイプラインに組み込んで自動化を実現
AIエージェント開発は、2026年のソフトウェア開発における最も重要なスキルの一つです。Claude Agent SDKを使いこなすことで、個人開発の生産性を飛躍的に向上させることができます。
まずはこの記事のコードレビューエージェントを実際に動かしてみてください。小さなエージェントから始めて、徐々にユースケースを広げていけば、あなたの開発ワークフローは大きく変わるはずです。