Claude Code Agent SDK — カスタムAIエージェント構築ガイド｜Python実装とマルチエージェント設計

Agent SDKとは — Claude Codeの機能をPythonで拡張

Claude Code Agent SDKは、Claude Codeの全ツール（Read、Write、Edit、Bash、Grep等）と機能をPythonスクリプトから利用できる公式SDKです。通常のClaude APIとは異なり、ファイルシステムアクセス、コマンド実行、マルチステップ推論といった「エージェント能力」が標準搭載されています。これにより、カスタムツールを追加したAIエージェント、複数のサブエージェントを協調させるマルチエージェントシステム、CI/CDパイプラインに組み込まれた自動化エージェントなど、Claude Codeの枠を超えた高度な実装が可能になります。品川区・港区のエンタープライズ企業では、Agent SDKでプルリクエスト自動レビュー、API仕様書の自動生成、テストケースの自動作成などを実装し、開発サイクルの大幅な加速を実現しています。

インストールと初期設定 — pip install claude-agent-sdk

Agent SDKのセットアップは非常にシンプルです： ```bash pip install claude-agent-sdk ``` 環境変数 `ANTHROPIC_API_KEY` にAPIキーを設定するか、コード内で明示的に指定します： ```python import os os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..." ``` **基本的なプロジェクト構成**： ``` project/ ├── agents/ │ ├── reviewer.py # コードレビューエージェント │ ├── doc_gen.py # ドキュメント生成エージェント │ └── utils.py # 共通ユーティリティ ├── .env # APIキー（Gitignore推奨） └── requirements.txt ``` 渋谷区のスタートアップでは、この構成で複数の専門エージェントを管理し、チーム全体で再利用しています。

query()とClaudeSDKClient — 基本的なエージェント実行

最もシンプルなエージェント実行は `query()` 関数を使う方法です： ```python from claude_agent_sdk import query result = query( "Analyze the codebase and identify potential security vulnerabilities", cwd="/path/to/project" ) print(result["output"]) ``` これだけで、Claude Codeの全機能（ファイル検索、コード解析、複数ファイルの読み取り）を使ったエージェントが実行されます。 **カスタムツールとHooksを使う場合** は `ClaudeSDKClient` を利用します： ```python from claude_agent_sdk import ClaudeSDKClient, Tool client = ClaudeSDKClient() result = client.query( prompt="Review this PR", tools=[custom_tool], hooks=[pre_commit_hook], cwd="/path/to/project" ) ``` 港区のWeb制作会社では、ClaudeSDKClientでプロジェクト固有のビルドツールやデプロイツールを追加し、完全自動化されたデリバリーパイプラインを構築しています。

カスタムツールの実装 — インプロセスMCPサーバー

Agent SDKの最大の特徴は、Python関数をそのままツールとして登録できる「インプロセスMCPサーバー」機能です。外部プロセスを立ち上げる必要がありません： ```python from claude_agent_sdk import Tool def check_test_coverage(path: str) -> dict: """Calculate test coverage for a given file.""" # pytest-cov等を使った実装 coverage = calculate_coverage(path) return {"coverage_percent": coverage, "status": "pass" if coverage > 80 else "fail"} coverage_tool = Tool( name="check_test_coverage", description="Calculate test coverage percentage for a source file", input_schema={ "type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"] }, function=check_test_coverage ) client = ClaudeSDKClient() result = client.query( "Check test coverage for all files in src/", tools=[coverage_tool] ) ``` エージェントは `check_test_coverage` ツールを他のClaude Code標準ツールと同様に使えます。品川区のSaaS企業では、社内データベースへのクエリツール、デプロイ状況確認ツール、顧客データ集計ツールなど、20種類以上のカスタムツールをAgent SDKで実装しています。

Hookの定義 — Python関数でライフサイクル制御

Agent SDKでは、Hooksも同様にPython関数で定義できます： ```python from claude_agent_sdk import Hook def validate_before_commit(context): """Run validation checks before git commit.""" if "git commit" in context.tool_input: # lint check result = subprocess.run(["npm", "run", "lint"], capture_output=True) if result.returncode != 0: return {"allow": False, "message": "Lint check failed. Fix errors before committing."} return {"allow": True} commit_hook = Hook( event="PreToolUse", tool="Bash", function=validate_before_commit ) client = ClaudeSDKClient() result = client.query( "Implement feature X and commit", hooks=[commit_hook] ) ``` Python実装のHookは、複雑な条件分岐、外部APIとの連携、データベースへのロギングなど、シェルコマンドでは難しい高度な処理を実現できます。渋谷区の開発チームでは、全コミット情報をSlackとJiraに自動送信するHookをPythonで実装しています。

サブエージェントの活用 — Task toolによるコンテキスト分離

Agent SDKは `Task` ツールを通じて**サブエージェント**を生成できます。サブエージェントは独立したコンテキストで動作し、親エージェントと並列に実行できます： ```python from claude_agent_sdk import ClaudeSDKClient client = ClaudeSDKClient() # 親エージェント result = client.query(""" Review this pull request: 1. Create a sub-agent to analyze code quality 2. Create another sub-agent to check security vulnerabilities 3. Aggregate results and generate a summary report """) ``` エージェントはプロンプト内で「Use the Task tool to create sub-agents for code quality and security analysis」と判断し、自動的に2つのサブエージェントを起動します。各サブエージェントは専門タスクに集中し、結果を親エージェントに返します。 **サブエージェントの利点**： - コンテキストウィンドウの分離（大規模プロジェクトでもトークン制限に引っかからない） - 並列実行による高速化 - 専門化によるタスク品質向上 港区のFinTech企業では、コードレビュー・セキュリティ監査・パフォーマンステスト・ドキュメント生成の4つのサブエージェントを並列実行し、PRレビュー時間を従来の1/4に短縮しました。

マルチエージェントオーケストレーション — リードエージェント+ワーカー構成

複雑なワークフローでは、**リードエージェント**がタスクを分割し、複数の**ワーカーエージェント**に配分する「オーケストレーションパターン」が有効です： ```python from claude_agent_sdk import ClaudeSDKClient import asyncio async def orchestrate_migration(): lead = ClaudeSDKClient() # リードエージェントがタスク分割 plan = await lead.query(""" Plan migration from MongoDB to PostgreSQL: 1. Analyze schema 2. Generate migration scripts 3. Create test fixtures 4. Write documentation Output: JSON task list """) tasks = parse_tasks(plan["output"]) # ワーカーエージェントを並列起動 workers = [ClaudeSDKClient() for _ in tasks] results = await asyncio.gather(*[ worker.query(task["prompt"]) for worker, task in zip(workers, tasks) ]) # 結果をマージ final = await lead.query(f"Aggregate results: {results}") return final result = asyncio.run(orchestrate_migration()) ``` このパターンは、大規模リファクタリング、マイクロサービス間の整合性チェック、マルチリポジトリの一括更新など、「複数の独立したサブタスクを協調させる」シナリオで威力を発揮します。品川区のプラットフォーム企業では、20個のマイクロサービスのAPI仕様を一括更新するオーケストレーターをAgent SDKで実装しています。

権限管理とセキュリティ — パーミッションモードとサンドボックス

Agent SDKは3段階の権限モードをサポートします： **1. interactive（デフォルト）** - 危険な操作は確認プロンプトを表示 **2. restricted** - 事前承認リストにない操作を全てブロック **3. autonomous** - 全ての操作を自動承認（信頼済み環境専用） ```python client = ClaudeSDKClient(permission_mode="restricted") client.add_allowed_commands(["npm test", "git status"]) ``` さらに、Agent SDKは**サンドボックス**機能を提供します（macOS: Seatbelt、Linux: bubblewrap）： ```python client = ClaudeSDKClient( sandbox=True, allowed_paths=["/project/src", "/project/tests"], blocked_network=True ) ``` これにより、エージェントは指定ディレクトリ外へのアクセス、ネットワーク通信、システムコマンドの実行ができなくなります。渋谷区のセキュリティ企業では、サードパーティ製プラグインの実行にサンドボックスを必須化しています。

CI/CDパイプライン統合 — GitHub ActionsでのAgent SDK利用

Agent SDKはCI/CD環境で真価を発揮します。GitHub Actionsの例： ```yaml name: AI Code Review on: pull_request: types: [opened, synchronize] jobs: ai-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' - run: pip install claude-agent-sdk - name: Run AI review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | python scripts/ai_reviewer.py --pr ${{ github.event.pull_request.number }} ``` `ai_reviewer.py` の実装： ```python from claude_agent_sdk import ClaudeSDKClient import os pr_number = os.environ["PR_NUMBER"] client = ClaudeSDKClient(permission_mode="restricted") result = client.query(f""" Review PR #{pr_number}: 1. Check code quality 2. Identify security issues 3. Suggest improvements Post review comments via GitHub API """) ``` 港区のSaaS企業では、このパターンで全PRに自動レビューを実装し、人間レビュアーは「AIが指摘した問題の妥当性チェック」に集中できるようになりました。レビュー時間が平均60%削減されています。

実践例: コードレビューエージェント — PR差分解析と修正提案

実用的なコードレビューエージェントの実装例： ```python from claude_agent_sdk import ClaudeSDKClient, Tool import subprocess import json def get_pr_diff(pr_number: int) -> str: """Fetch PR diff from GitHub.""" result = subprocess.run( ["gh", "pr", "diff", str(pr_number)], capture_output=True, text=True ) return result.stdout def post_review_comment(pr_number: int, body: str, path: str, line: int): """Post review comment to GitHub PR.""" subprocess.run([ "gh", "pr", "review", str(pr_number), "--comment", "--body", body, "--path", path, "--line", str(line) ]) gh_tools = [ Tool(name="get_pr_diff", function=get_pr_diff, ...), Tool(name="post_review_comment", function=post_review_comment, ...) ] client = ClaudeSDKClient() result = client.query( f"Review PR #{pr_number}. For each issue found, post a review comment with specific line references and improvement suggestions.", tools=gh_tools ) ``` このエージェントは、PR差分を取得→問題点を特定→該当行にコメント投稿まで、完全自動で実行します。品川区の開発チームでは、このエージェントが「変数名のtypo」「未使用import」「エラーハンドリング不足」などを90%以上の精度で検出しています。

実践例: ドキュメント生成エージェント — コードからAPI仕様書を自動生成

Agent SDKでAPI仕様書を自動生成する実装： ```python from claude_agent_sdk import ClaudeSDKClient client = ClaudeSDKClient() result = client.query(""" Analyze all API endpoints in src/api/ and generate OpenAPI 3.0 specification: 1. Extract route definitions, parameters, response types 2. Read JSDoc/docstrings for descriptions 3. Generate openapi.yaml with complete schemas 4. Validate the generated spec """) if result["success"]: print("API documentation generated at docs/openapi.yaml") ``` エージェントは以下を自動実行： - 全APIエンドポイントファイルの検索（Glob） - 各ファイルの読み取り（Read） - ルート定義とパラメータの抽出 - OpenAPI仕様の生成（Write） - 仕様の妥当性検証（Bash: openapi-validator） 渋谷区のAPI開発チームでは、コード変更のたびにこのエージェントをCI/CDで実行し、ドキュメントが常に最新に保たれています。「ドキュメント更新忘れ」問題が完全に解消されました。

エンタープライズ活用とオブライトのサポート

Agent SDKのエンタープライズ導入では、以下の要素が重要です： **1. SSO/SCIM統合** - Anthropicのエンタープライズプランは、Okta、Azure AD等とのSSO/SCIMに対応。Agent SDKで作成した自動化エージェントも、同じ認証基盤で管理できます。 **2. 監査ログ** - 全エージェント実行の監査ログをCloudWatch、Datadog等に送信する標準実装。 **3. コスト管理** - エージェントごとのトークン使用量追跡。予算超過時の自動停止機構。 **4. チーム共有エージェントライブラリ** - 社内で再利用可能なエージェントをライブラリ化し、全チームで共有。 品川区・港区エリアの株式会社オブライトでは、Agent SDKを使ったエンタープライズAI開発環境の構築支援を提供しています。カスタムツール設計、マルチエージェントアーキテクチャ設計、セキュリティ設定、CI/CD統合まで、導入から運用まで一貫してサポートいたします。

まとめ — Agent SDKで実現するAIファーストな開発環境

Claude Code Agent SDKは、「AIエージェントを開発ツールとして組み込む」未来を現実にします。カスタムツールによる業務システムとの統合、マルチエージェントによる複雑タスクの分散処理、CI/CDパイプラインへの組み込みによる継続的な自動化——これらすべてがPythonの知識だけで実現できます。品川区・港区・渋谷区エリアでAgent SDKを活用したAI開発環境の導入をお考えの企業様は、株式会社オブライトにご相談ください。プロトタイプ開発から本番運用、チーム教育まで、実績豊富なエンジニアが貴社のAI活用を加速します。