# Claude Agent SDKの便利だけど知られていない機能 🌍 セッション途中で権限を変えたい？ストリーミング中に権限モードを動的に切り替えられます！ Claude Agent SDKでは、セッション実行中に `set_permission_mode()` を呼ぶだけで、権限モードを即座に変更できます。 📌 タイトル：ストリーミング中の権限モード動的変更 🔗 URL： 🧩 概要 `set_permission_mode()`（Python）/ `setPermissionMode()`（TypeScript）を使うと、セッションの途中で権限モードをリアルタイムに変更できます。新しいモードは即座に有効となり、以降のすべてのツールリクエストに適用されます。「最初は厳格に、信頼が築けたら緩める」という段階的な権限管理が実現できます。 🛠 使い方 ```python # Python - 段階的に権限を緩和する例 import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions async def main(): async with ClaudeSDKClient( options=ClaudeAgentOptions( permission_mode="default", # まずはデフォルトで開始 ) ) as client: await client.query("このコードをリファクタリングしてください") # アプローチを確認後、編集を許可 await client.set_permission_mode("acceptEdits") async for message in client.receive_response(): if hasattr(message, "result"): print(message.result) ``` ```typescript // TypeScript const q = query({ prompt: "Refactor this code", options: { permissionMode: "default" } }); // アプローチ確認後に編集を許可 await q.setPermissionMode("acceptEdits"); for await (const message of q) { if ("result" in message) console.log(message.result); } ``` 🏗 本番システムへの組み込み方 ・「plan → 確認 → acceptEdits」のワークフローで、安全なステップバイステップの自動化を実現します ・ユーザーの信頼度や操作の進行状況に応じて、段階的に権限を拡大するインタラクティブなアプリを構築できます ・エラー検出時に権限を引き締める「フォールバック」パターンにも活用できます ・監視システムと連携し、異常検知時に自動的に制限的なモードへ切り替えることも可能です 💡 ユースケース 🔐 コードレビュー後に編集権限を付与する対話型ワークフロー 📈 タスクの進捗に応じて権限を段階的に拡大するプログレッシブな自動化 🛡 異常を検知したら即座に制限モードに切り替える防御的エージェント ⚠️ 注意点 ・新しいモードは即座に有効になるため、切り替えのタイミングに注意してください ・モード変更は現在のセッション内でのみ有効です ・`bypassPermissions` や `auto` モードに切り替えた場合、サブエージェントにも継承される点に注意が必要です ✨ 権限の動的変更は「最初は安全に、必要に応じて柔軟に」を実現する強力なツールです。段階的な信頼構築のワークフローにぜひ活用してください！ #ClaudeAgentSDK# #AIAgent#

# Claude Agent SDKの便利で実践的な使い方 🤖 サブエージェントに専門タスクを委譲して、メインコンテキストをリーンに保てます。 サブエージェントは、特定のサブタスクを専門エージェントに委譲し、メインエージェントのコンテキストを汚さずに並列・専門処理を実現する機能です。 📌 タイトル：SDK のサブエージェント 🔗 URL： 🧩 概要 `agents` パラメータで専門エージェントを定義し、メインエージェントが `Agent` ツール経由で呼び出します。各サブエージェントには独自のプロンプト・ツール制限・モデル設定が可能で、結果は要約としてメインに返されます。 🛠 使い方 `agents` パラメータに `AgentDefinition`（`description`・`prompt`・`tools`・`model` 等）を定義します。`allowed_tools` に `"Agent"` を含めるとサブエージェント呼び出しが自動承認されます。各サブエージェントは独自のツール制限・プロンプト・モデルを持てます。 🏗 実践的な使い方 ・`research-assistant` サブエージェントに数十ファイルの探索を委譲し、親エージェントには要約だけ返します。メインコンテキストがリーンに保たれます。 ・`style-checker` / `security-scanner` / `test-coverage` を同時実行し、コードレビュー時間を数分→数秒に短縮します。 ・`database-migration` サブエージェントに SQL ベストプラクティス・ロールバック戦略のプロンプトを持たせ、メインを汚さず専門タスクを処理します。 ・ファクトリ関数で実行時条件に応じて `model: "opus"` / `sonnet` を動的に切り替えます。 💡 ユースケース 🔍 大量ファイル探索の委譲 ⚡ 並列コードレビュー（style/security/coverage） 🎯 専門知識エージェントへのタスク分割 ⚠️ 注意点 サブエージェントは自分のサブエージェントを生成できません（1 段階のみ）。大規模オーケストレーションには `Workflow` ツール（TS v0.3.149+）を使用してください。`agentId` と `session_id` をキャプチャすれば `resume` でフォローアップも可能です。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利だけど知られていない機能 🌍 コードを変更せずに計画だけ立ててほしい？planモードなら読み取り専用でClaudeが分析・提案します！ Claude Agent SDKのplanモードは、ソースファイルを一切編集せず、読み取り専用ツールだけでコードを探索し、変更計画を立てるモードです。 📌 タイトル：plan モード（読み取り専用のみ実行） 🔗 URL： 🧩 概要 `permission_mode="plan"` を設定すると、Claudeは読み取り専用ツール（Read、Grep、Globなど）と読み取り専用のシェルコマンドだけを使ってコードベースを探索します。Edit、Write、Bashでの書き込み操作は実行されません。要件の明確化が必要な場合は `AskUserQuestion` を使ってユーザーに質問することもあります。コードレビューや変更提案を安全に行いたい場面で最適です。 🛠 使い方 ```python # Python - コードレビュー用のplanモード import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="認証モジュールのセキュリティ問題を分析し、改善計画を提案してください", options=ClaudeAgentOptions( permission_mode="plan", # 読み取り専用で分析 ), ): if hasattr(message, "result"): print(message.result) ``` ```typescript // TypeScript for await (const message of query({ prompt: "Analyze security issues in the auth module and propose a fix plan", options: { permissionMode: "plan" // Read-only analysis } })) { if ("result" in message) console.log(message.result); } ``` 🏗 本番システムへの組み込み方 ・プルリクエストの自動レビューで、コードを変更せず問題点と改善案だけを提示します ・新しいコードベースの調査・理解フェーズで安全に探索できます ・変更を実行する前の「計画フェーズ」として、人間が計画を確認してから実行モードに切り替える運用ができます ・`set_permission_mode()` と組み合わせて、計画承認後に `acceptEdits` に切り替えるワークフローが構築できます 💡 ユースケース 📋 コードレビューで変更提案だけを生成し、実際の変更は人間が判断する 🔍 大規模コードベースのアーキテクチャ分析を安全に行う 📝 リファクタリング計画を立てて、チームで合意してから実行する ⚠️ 注意点 ・読み取り専用のシェルコマンドは実行される場合があります ・`AskUserQuestion` が発生する可能性があるため、完全な無人実行にはdontAskモードの方が適しています ・計画結果を実行に移す場合は、新しいセッションまたは権限モードの動的変更が必要です ✨ 「まず計画、次に実行」のワークフローはエンジニアリングの基本です。planモードで安全に分析し、納得してから変更を実行しましょう！ #ClaudeAgentSDK# #AIAgent#

# Claude Agent SDKの便利で実践的な使い方 🔌 MCP で Playwright・DB・GitHub 等の外部ツールをエージェントに接続して、能力を無限に拡張できます。 MCP（外部ツール接続）は、Model Context Protocol を介して外部の MCP サーバー（ブラウザ・DB・API 等）をエージェントに接続する機能です。 📌 タイトル：MCP を使用して外部ツールに接続する 🔗 URL： 🧩 概要 `mcp_servers` に stdio / HTTP / SSE トランスポートで外部 MCP サーバーを指定します。`allowedTools` でアクセス可能なツールを制御し、`env` や `headers` で認証情報を注入します。 🛠 使い方 `mcp_servers` に stdio / HTTP / SSE トランスポートでサーバーを指定します。例えば Playwright は `{"command": "npx", "args": ["@playwright/mcp@latest"]}`、Postgres は `"env": {"DATABASE_URL": "..."}` で接続情報を注入します。`allowed_tools=["mcp__postgres__query"]` で利用可能なツールを制御します。 🏗 実践的な使い方 ・Playwright MCP サーバーを接続し「 を開いて内容を説明して」で E2E テストや Web スクレイピングエージェントを構築します。 ・Postgres MCP サーバーに接続し「先週のサインアップ数を日別で」と尋ねると、Claude がスキーマ検出→ SQL 生成→実行します。`allowedTools: ["mcp__postgres__query"]` で読み取りのみ許可。 ・GitHub MCP サーバーで Issue トリアージや自動対応ボットを構築します。 ・`system/init` メッセージの `mcp_servers[].status` で接続状態を起動前に検証します。 💡 ユースケース 🌐 Playwright によるブラウザ自動化 🗄 自然言語での DB クエリ実行 📋 GitHub Issue の自動トリアージ ⚠️ 注意点 `permissionMode: "acceptEdits"` は MCP ツールを自動承認しません。`allowedTools` のワイルドカード（`mcp__github__*`）で必要なサーバーのみ許可するのが安全です。接続タイムアウトはデフォルト 60 秒です。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利で実践的な使い方 🔧 社内 API・DB・ドメインロジックを `@tool` で定義して、Claude に呼び出させましょう。 カスタムツールは、`@tool` デコレータでインプロセス MCP サーバーとして独自関数を定義し、Claude が会話中に呼び出せるようにする機能です。 📌 タイトル：Claude にカスタムツールを提供する 🔗 URL： 🧩 概要 `@tool`（Python）/ `tool()`（TypeScript）で名前・説明・スキーマ・ハンドラーを定義し、`create_sdk_mcp_server` でラップして `mcp_servers` に渡します。副作用のないツールには `readOnlyHint: true` を付けて並列実行を最適化できます。 🛠 使い方 `@tool`（Python）/ `tool()`（TypeScript）で名前・説明・スキーマ・ハンドラーを定義し、`create_sdk_mcp_server` でラップして `mcp_servers={"weather": server}` に渡します。ツール名は `mcp__weather__get_temperature` の形式で Claude に公開されます。 🏗 実践的な使い方 ・社内 API（顧客情報・在庫・注文状況等）を `@tool` で定義し、自然言語での問い合わせに対応するエージェントを構築します。 ・`readOnlyHint: true` を読み取り専用ツールに付与し、複数ツールの同時実行でレイテンシを削減します。 ・ハンドラー内で例外を握りつぶし `is_error=True` を返すと、エージェントループは継続し Claude がリトライ・代替手段を試みます。 ・チャート生成ツールが `image` ブロック（base64）でグラフ画像を返し、Claude に結果を分析させます。 💡 ユースケース 🏢 社内 API への自然言語アクセスエージェント 📊 グラフ生成＋画像分析パイプライン 🔄 エラー耐性のある自律リトライ ⚠️ 注意点 ハンドラー内でキャッチされない例外は `query()` 全体を落とすため、必ずエラーハンドリングを行ってください。`tools: ["Read","Grep"]` で組み込みツールの利用を制限することも可能です。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利で実践的な使い方 📦 エージェントの出力を型付き JSON で受け取り、UI コンポーネントに直接バインドできます。 構造化出力は、`output_format` でエージェントの最終出力を JSON スキーマに従った型付きデータとして取得する機能です。Zod / Pydantic で型安全に検証できます。 📌 タイトル：エージェントから構造化された出力を取得する 🔗 URL： 🧩 概要 `output_format` に JSON スキーマを指定すると、エージェントはツール実行・分析の結果を自由文ではなく構造化 JSON で返します。Zod（TypeScript）/ Pydantic（Python）で型安全に検証可能です。 🛠 使い方 `output_format={"type": "json_schema", "schema": your_schema}` をオプションに設定します。Pydantic の `.model_json_schema()` や Zod の `z.toJSONSchema()` でスキーマを生成できます。結果は `ResultMessage.structured_output` に格納されます。 🏗 実践的な使い方 ・レシピアプリで Web 検索結果を `{name, prep_time_minutes, ingredients[], steps[]}` の型付き JSON で受け取り、UI コンポーネントへ直接バインドします。 ・TODO 抽出エージェントで Grep + Bash(git blame) を自律実行し `{todos[{text, file, line, author?, date?}], total_count}` を返します。 ・機能実装計画を `{summary, steps[{description, complexity}], risks[]}` のスキーマで受け取り、プロジェクト管理ツールに自動投入します。 💡 ユースケース 🎨 UI コンポーネントへの直接データバインディング 📊 分析結果の構造化レポート生成 🔧 プロジェクト管理ツールへの自動データ投入 ⚠️ 注意点 構造化出力はストリーミングと非互換です。JSON 結果は最終 `ResultMessage.structured_output` にのみ出力されます。`error_max_structured_output_retries` を検知して、より単純なプロンプトでの再試行や非構造化フォールバックを実装してください。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利で実践的な使い方 ✅ 危険な操作の前にユーザー承認を求め、6 種類の応答パターンで柔軟に制御できます。 承認とユーザー入力の処理は、`canUseTool` コールバックで危険操作を検知してユーザーに確認を求め、`AskUserQuestion` で要件収集を行う機能です。 📌 タイトル：承認とユーザー入力を処理する 🔗 URL： 🧩 概要 `canUseTool` で各ツール呼び出しをインターセプトし、承認/拒否/代替案提案など 6 パターンの応答が可能です。`AskUserQuestion` ツールでは、Claude がユーザーに複数選択肢の質問を投げて要件を収集できます。 🛠 使い方 `canUseTool` コールバックを定義し、ツール名・引数に基づいて `PermissionResultAllow` / `PermissionResultDeny` を返します。 🏗 実践的な使い方 ・ファイル削除や Bash 実行を検知して y/n を問う対話的承認 UI を構築します。「全 Bash コマンドを `/tmp/sandbox` にスコープ」のように変更を加えて承認することも可能です。 ・「承認して記憶」パターンで `updated_permissions` を使い、`.claude/settings.local.json` に永続化します。 ・`AskUserQuestion` で「モバイルアプリのテックスタック」について選択肢を提示し、`plan` モードと組み合わせて変更前に要件収集する対話ワークフローを実現します。 💡 ユースケース 🛡 危険操作の対話的承認 UI 📋 複数選択肢による要件収集 🔐 承認ルールの永続化による学習 ⚠️ 注意点 サブエージェントでは AskUserQuestion は使用できません。質問は 1〜4 個、選択肢は 2〜4 個の制限があります。Python では `can_use_tool` にストリーミングモードとダミー PreToolUse フックが必要です。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利だけど知られていない機能 🌍 AIがファイルを変更しても、いつでも元に戻せる安心感。 ファイルチェックポイントを使えば、Write/Edit/NotebookEditによる変更を自動追跡し、任意の時点にロールバックできます。 📌 タイトル：ファイルチェックポイントとロールバック 🔗 URL： 🧩 概要 ファイルチェックポイントは、エージェントセッション中のファイル変更を追跡する機能です。enable_file_checkpointing=Trueを設定すると、Write・Edit・NotebookEditツールによるファイル変更前にバックアップが自動作成されます。各UserMessageのUUIDがチェックポイントとして機能し、rewind_files()でそのUUID時点の状態に復元できます。新規作成されたファイルは削除され、変更されたファイルは元の内容に戻ります。 🛠 使い方 ```python import asyncio from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage, ) async def main(): # Step 1: チェックポイントを有効化 options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", extra_args={"replay-user-messages": None}, # UUID取得に必須 ) checkpoint_id = None session_id = None async with ClaudeSDKClient(options) as client: await client.query("認証モジュールをリファクタリングして") # Step 2: UserMessageからチェックポイントUUIDを取得 async for message in client.receive_response(): if isinstance(message, UserMessage) and message.uuid and not checkpoint_id: checkpoint_id = message.uuid if isinstance(message, ResultMessage) and not session_id: session_id = message.session_id # Step 3: セッションを再開してロールバック if checkpoint_id and session_id: async with ClaudeSDKClient( ClaudeAgentOptions( enable_file_checkpointing=True, resume=session_id ) ) as client: await client.query("") # 空プロンプトで接続を開く async for message in client.receive_response(): await client.rewind_files(checkpoint_id) break print(f"チェックポイントに巻き戻しました: {checkpoint_id}") ``` 🏗 本番システムへの組み込み方 ・extra_args={"replay-user-messages": None}は必須です。これがないとUUIDがストリームに含まれません ・ロールバック時はセッションをresumeで再開し、空プロンプトで接続後にrewind_files()を呼びます ・チェックポイントUUIDとセッションIDを永続化しておけば、プロセス再起動後もロールバック可能です ・permission_mode="acceptEdits"と組み合わせることで、ファイル変更を自動承認しつつ安全にロールバックできます 💡 ユースケース 🔧 安全なリファクタリング：変更を試して、問題があれば即座にロールバック 🧪 実験的コード生成：AIの出力を検証し、品質が低ければ元に戻す 📝 ドキュメント自動生成：生成結果をレビューして、不要な変更だけ取り消し ⚠️ 注意点 ・Bashコマンド（echo > file.txt、sed -i 等）による変更は追跡されません ・チェックポイントはファイルの内容のみを追跡します。ディレクトリの作成・移動・削除は元に戻りません ・会話履歴はロールバックされません。ファイルのみが復元されます ・チェックポイントは作成したセッションに紐づいています ✨ 「取り消し」できるAI開発で、安心してコードを任せましょう！ #ClaudeAgentSDK# #AIAgent#

# Claude Agent SDKの便利で実践的な使い方 🛡 プロンプトインジェクション対策・認証情報プロキシ・最小権限で多層防御を構築しましょう。 セキュアデプロイメントは、分離技術・認証情報プロキシ・ネットワーク制御でエージェントの安全な本番運用を実現するガイドです。 📌 タイトル：AI エージェントの安全なデプロイ 🔗 URL： 🧩 概要 sandbox-runtime / Docker / gVisor / Firecracker の分離技術、認証情報プロキシパターン、ネットワーク・ファイルシステム制御を組み合わせた多層防御を提供します。 🛠 使い方 分離強度に応じて技術を選択：単一開発者/CI は sandbox-runtime、マルチテナントは gVisor/Firecracker。認証情報は Envoy / mitmproxy / LiteLLM で境界外注入します。 🏗 実践的な使い方 ・認証情報プロキシパターン：API キーをエージェント境界外のプロキシで注入し、エージェントは認証情報を見ずに API 呼び出しします。`ANTHROPIC_BASE_URL` でルーティング。 ・最小権限：必要ディレクトリのみ読み取り専用マウント、`.env`・`~/.aws/credentials`・`*.pem` を除外、`--network none` + Unix ソケットプロキシでネットワーク制限。 ・クラウドではプライベートサブネット + クラウドファイアウォールでプロキシ以外の送信を全ブロックし、許可リスト強制・認証情報注入・全トラフィックログを実現します。 💡 ユースケース 🔐 認証情報のエージェント境界外管理 🌐 ネットワーク制限による外部送信の防止 🏢 マルチテナント環境での強分離 ⚠️ 注意点 信頼できないコンテンツ（README、Web ページ、ユーザー入力）にはプロンプトインジェクションが含まれる可能性があります。ネットワーク制御は最後の防衛線として必ず設定してください。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利で実践的な使い方 📏 長時間のエージェント実行でコンテキストが溢れる心配はありません。自動圧縮が履歴を賢く管理します。 コンテキストウィンドウと自動圧縮は、長時間実行エージェントで古い履歴を自動要約し、コンテキスト上限を超えずに動作を継続させる仕組みです。 📌 タイトル：コンテキストウィンドウ 🔗 URL： 🧩 概要 エージェントが長時間動作し続けると、ツール呼び出し履歴でコンテキストが膨張します。SDK はコンテキスト上限接近時に古い履歴を自動要約（圧縮）し、重要な情報を維持しながら動作を継続します。`PreCompact` フックで圧縮前に完全トランスクリプトをアーカイブすることも可能です。 🛠 使い方 自動圧縮はデフォルトで有��です。`compact_boundary` メッセージを監視して圧縮タイミングをログに記録できます。`PreCompact` フックで圧縮前のアーカイブ処理を追加できます。 🏗 実践的な使い方 ・圧縮で失われたくない恒久的ルール（タスク目標、変更したファイルパス、テスト結果、決定理由）は CLAUDE.md に書くことで、毎リクエスト再注入されます。 ・`PreCompact` フックで圧縮前の完全トランスクリプトを外部ストレージにアーカイブし、監査ログとして保持します。 ・長尺のリファクタリングタスクで、数十回のツール呼び出し履歴が自動的に要約され、最新のコンテキストに集中して作業を継続できます。 💡 ユースケース 📝 長時間のリファクタリング・デバッグタスク 🗄 監査ログ用の完全トランスクリプト保存 🎯 CLAUDE.md による恒久ルールの維持 ⚠️ 注意点 圧縮により古い履歴の詳細は失われます。絶対に保持したい情報は初期プロンプトではなく CLAUDE.md に記述することで、圧縮の影響を受けません。 #ClaudeAgentSDK# #AI#