# 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#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ストリーミング中のエージェント実行を、ユーザーの操作でただちに停止できることをご存知ですか？ `RunResultStreaming.cancel()` を使えば、ストリーミング実行を途中で安全にキャンセルできます。 📌 タイトル：RunResultStreaming.cancel() 🔗 URL： 🧩 概要 `RunResultStreaming` の `cancel()` メソッドを呼ぶと、ストリーミング中のエージェント実行を即座に、または現在のターン完了後に停止できます。キャンセル後もクリーンアップのために `stream_events()` の非同期イテレータを最後まで消費する必要があります。`is_complete` プロパティでランが終端状態に達したかどうかを確認でき、`final_output` や `interruptions` などのサマリプロパティは最後のトークン後に確定します。 🛠 使い方 ```python from agents import Agent, Runner agent = Agent(name="Assistant", instructions="You are helpful.") result = "Write a long essay...") async for event in # ユーザーがキャンセルボタンを押した場合 if user_cancelled(): result.cancel() # キャンセル後もイテレータを最後まで消費する continue # 通常のイベント処理 handle_event(event) # クリーンアップ完了後に状態を確認 print(f"Complete: {") ``` 🏗 本番システムへの組み込み方 ・チャット UI の「停止」ボタンと連携し、ユーザー主導のキャンセルを実装する ・キャンセル後も `stream_events()` を最後まで消費してリソースリークを防ぐ ・`is_complete` を確認し、キャンセルされた実行と正常完了を区別してログに記録する ・コスト管理として、不要な生成を早期に打ち切りトークン消費を抑える 💡 ユースケース 🛑 チャットボットの「生成停止」ボタン実装 💰 長大な応答のトークンコスト削減 ⏱ タイムアウトベースの自動キャンセル 🔄 ユーザーが質問を変更した際の前回実行の中断 ⚠️ 注意点 `cancel()` を呼んだ後に `stream_events()` の消費をスキップすると、リソースのクリーンアップが正しく行われません。必ずイテレータを最後まで走らせてください。また、キャンセルのタイミングによっては現在のターンが完了するまで停止しない場合があります。 ✨ cancel() で、ユーザーが主導権を持てるレスポンシブなストリーミング体験を実現しましょう。 #OpenAIAgentSDK# #AIAgent#

# Claude Agent SDKの便利だけど知られていない機能 🌍 システムプロンプトをゼロから書く必要はありません。claude_code プリセットに append で追記する方式を使えば、安全性やツールガイダンスを維持したまま独自の指示を追加できます。 さらに excludeDynamicSections で複数マシン間のプロンプトキャッシュ共有も可能です。 📌 タイトル：システムプロンプトのプリセット+追記方式 🔗 URL： 🧩 概要 Claude Agent SDK のシステムプロンプトには3つの出発点があります。(1) ミニマルデフォルト（`systemPrompt` 未設定時、ツール呼び出しのみカバー）、(2) `claude_code` プリセット（Claude Code CLI と同じフルプロンプト）、(3) カスタム文字列（完全に独自のプロンプト）。特に便利なのが `claude_code` プリセット + `append` の組み合わせで、プリセットが提供するツール使用ガイダンス、安全性ルール、コーディング規約をすべて維持しつつ、末尾に独自の指示を追加できます。CLAUDE.md はシステムプロンプトではなく会話に注入される点も重要です。 🛠 使い方 `system_prompt` に dict 形式でプリセットと append を指定します。 ```python from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Help me write a Python function to calculate fibonacci numbers", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", "append": "Always include detailed docstrings and type hints in Python code.", } ), ): pass # メッセージを処理 # excludeDynamicSections でキャッシュ共有を有効化 async for message in query( prompt="Triage the open issues in this repo", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", "append": "You operate Acme's internal triage workflow.", "exclude_dynamic_sections": True, # 環境依存部分を除外 }, ), ): pass ``` 🏗 本番システムへの組み込み方 ・コーディングエージェントを構築する場合は `claude_code` プリセット + `append` を基本形とし、セキュリティルールやツールガイダンスの再実装コストを削減できます ・`exclude_dynamic_sections: True` を指定すると、作業ディレクトリやOS情報などの動的コンテキストがシステムプロンプトからユーザーメッセージに移動し、異なるマシン間でプロンプトキャッシュを共有できます ・CLAUDE.md は `setting_sources` に `"project"` を含めることで自動読み込みされ、システムプロンプトとは独立して機能します 💡 ユースケース 🏢 社内コーディング標準の適用：プリセットの安全性を維持しつつ、社内規約を append で追加する 🌐 多拠点展開のコスト削減：excludeDynamicSections でプロンプトキャッシュを全マシンで共有する 🤖 特化型エージェント：データ分析やサポートボットなど、コーディング以外の用途にはカスタム文字列を使用する ⚠️ 注意点 ・カスタム文字列を使う場合、ツールガイダンスや安全性ルールは自分で記述する必要があります ・`excludeDynamicSections` を有効にすると、環境情報がユーザーメッセージに移動するため、指示としての重みがわずかに低下する可能性があります ・SDK デフォルト（`systemPrompt` 未設定）は Claude Code CLI のデフォルトとは異なります。CLI からの移行時は明示的にプリセットを設定してください ✨ プリセット+追記方式は「安全な既定値を壊さずにカスタマイズする」最もリスクの低い方法です。 #ClaudeAgentSDK# #AIAgent#

# Claude Agent SDKの便利で実践的な使い方 ⏪ エージェントが行ったファイル変更を追跡し、いつでも安全な状態に巻き戻せます。 ファイルチェックポイントは、エージェントが Write/Edit で行った変更を追跡し、`rewind_files()` で任意の時点に巻き戻す機能です。 📌 タイトル：checkpointing でファイル変更を巻き戻す 🔗 URL： 🧩 概要 `enable_file_checkpointing=True` で有効化すると、各ターンの変更が追跡されチェックポイント UUID が発行されます。`rewind_files(checkpoint_id)` で指定時点のファイル状態に復元できます。 🛠 使い方 `enable_file_checkpointing=True` で有効化します。ストリーム中の `UserMessage.uuid` がチェックポイント ID になります。復元は `rewind_files(checkpoint_id)` を呼び出します（CLI では `--rewind-files` フラグ）。 🏗 実践的な使い方 ・リスク操作前に最新チェックポイント UUID を保持し、検証失敗時に直前の安全状態へ即巻き戻します。 ・ターン毎の UUID を配列保存し、「ターン 1 のリファクタは残しつつ、ターン 2 のテスト追加だけ元に戻す」といった選択的ロールバックを実現します。 ・ドキュメントコメント追加後にユーザーへ「巻き戻すか？」を確認する対話的承認フローを構築します。 💡 ユースケース 🛡 検証失敗時の安全な状態への即時復元 🎯 選択的ロールバック（特定ターンのみ巻き戻し） 🔄 試行錯誤サイクルの高速化 ⚠️ 注意点 Bash 経由（`echo >`, `sed -i`）の変更・ディレクトリ操作・リモートファイルは追跡対象外です。会話履歴は巻き戻されません（ファイルのみ）。 #ClaudeAgentSDK# #AI#

# Claude Agent SDKの便利で実践的な使い方 🔐 ツールアクセスを段階的に制御して、安全と生産性のバランスを取りましょう。 パーミッションの設定は、`allowed_tools` / `disallowed_tools` / `permission_mode` でエージェントのツール利用を多段階に制御し、安全な運用を実現する機能です。 📌 タイトル：パーミッションの設定 🔗 URL： 🧩 概要 評価順序は「フック→拒否ルール→パーミッションモード→許可ルール→canUseTool」です。`disallowed_tools` はスコープ付き拒否（例: `Bash(rm *)`）に対応し、`bypassPermissions` でもブロックされる最終防衛線です。 🛠 使い方 `allowed_tools` で自動承認するツールを、`disallowed_tools` でブロックするツール（スコープ付き拒否も可：`"Bash(rm *)"`）を、`permission_mode` で全体のモード（`default` / `acceptEdits` / `dontAsk` / `plan` / `bypassPermissions`）を設定します。 🏗 実践的な使い方 ・`allowedTools: ["Read","Glob","Grep"]` + `permissionMode: "dontAsk"` で許可ツール以外は即拒否する読み取り専用ロックダウンを構築します。 ・`default` で開始し、初期アプローチをレビュー後に `acceptEdits` へ動的切替。プロトタイピングの反復を高速化します。 ・`plan` モードで読み取り専用ツールのみ実行し、Claude にソース変更なしで計画だけ立てさせます。コードレビューや変更前承認フローに最適です。 ・CI/隔離環境では `bypassPermissions` を使用しつつ、`disallowed_tools=["Bash(rm -rf /)"]` で最終防衛線を設けます。 💡 ユースケース 🔒 読み取り専用のコード分析エージェント 📋 plan モードによる変更前承認フロー 🚀 段階的信頼レベルの動的切替 ⚠️ 注意点 `allowed_tools` は `bypassPermissions` を制限しません。危険操作のブロックには必ず `disallowed_tools` を使用してください。サブエージェントは親のパーミッションモードを継承し、上書きできません。 #ClaudeAgentSDK# #AI#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 ガードレールで、エージェントの入出力を安全に制御しましょう！ 安価な高速モデルで事前チェックを行い、不適切なリクエストをブロックしてコストを削減できます。 📌 タイトル：Guardrails 🔗 URL： 🧩 概要 Guardrailsは、エージェントの入力と出力に対してチェックを実行する仕組みです。入力ガードレール（Input guardrails）はユーザー入力を検証し、出力ガードレール（Output guardrails）はエージェントの応答を検証します。安価な高速モデルをガードレールに使い、高価なモデルの不要な実行を防ぐことで、コスト最適化を実現できます。トリップワイヤー方式で、問題を検出した時点で実行を即座に中断します。 🛠 使い方 `agents`から`Agent`, `InputGuardrail`, `OutputGuardrail`, `GuardrailFunctionOutput`をインポートします。ガードレール関数`check_homework_request(context, agent, input_data)`を定義し、内部で` input_data)`を呼び出して分類結果を取得します。戻り値は`GuardrailFunctionOutput(output_info= tripwire_triggered="TutorBot", instructions="You are a tutoring assistant.", input_guardrails=[InputGuardrail(guardrail_function=check_homework_request)])`のように定義します。 🏗 実践的な使い方 **安価モデルによる事前フィルタリング（コスト削減）** 高価なメインモデルを実行する前に、安価な高速モデルで「宿題の代行」「不正利用」などを検出してブロックします。トリップワイヤーが発動すると、メインモデルの実行がスキップされるためコスト削減になります。 安価な分類用エージェント`Agent(name="Classifier", model="gpt-4o-mini", output_type=ClassificationResult)`を定義し、`abuse_check`関数内で` input_data)`を実行します。`tripwire_triggered="Assistant", model="gpt-4o", input_guardrails=[InputGuardrail(guardrail_function=abuse_check)])`に設定します。 **出力ガードレールによるコンテンツチェック** エージェントの応答に機密情報や不適切な内容が含まれていないかを検証します。 出力ガードレール関数`check_sensitive_output(context, agent, output)`を定義し、` f"Check this output for sensitive content: {output}")`で機密情報の有無を判定します。`tripwire_triggered="SupportBot", output_guardrails=[OutputGuardrail(guardrail_function=check_sensitive_output)])`のように設定します。 **サポートボットの関連性チェック** ユーザーの質問がサポート範囲内かを事前に判定し、範囲外の質問には早期に対応します。 関連性チェック関数`relevance_check(context, agent, input_data)`で` input_data)`を実行し、`tripwire_triggered=not "SupportBot", instructions="Answer customer support questions about our product.", input_guardrails=[InputGuardrail(guardrail_function=relevance_check)])`として設定します。 💡 ユースケース 🛡 宿題代行・不正利用リクエストのブロック（コスト削減） 🔍 機密情報の出力防止（PII、社内情報の漏洩防止） 📋 サポートボットの対応範囲制御 ⚡ 安価モデルによる事前スクリーニングでAPI費用を最適化 ⚠️ 注意点 - ガードレールのトリップワイヤーが発動すると`InputGuardrailTripwireTriggered`例外が発生します。適切にキャッチして処理してください - 入力ガードレールはメインモデルと**並列**で実行されるため（デフォルト）、ガードレールが間に合わない場合はメインの実行が進む可能性があります - ガードレール自体のモデル呼び出しコストも考慮してください - 複数のガードレールを設定でき、いずれかが発動すれば中断されます ✨ ガードレールを活用して、安全性とコスト効率を両立したエージェントを構築しましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 LLM の出力を「文字列のまま祈る」のではなく、型安全な構造化データとして受け取りましょう。output_type を使えば、壊れた JSON に悩まされる日々とはお別れです。 output_type に Pydantic モデル・dataclass・TypedDict を指定するだけで、エージェントの出力が自動的にバリデーション済みの構造化データになります。 📌 タイトル：Agents -- Output types 🔗 URL： 🧩 概要 Agent の `output_type` パラメータを設定すると、LLM の出力が Structured Outputs として強制されます。Pydantic BaseModel、dataclass、TypedDict のいずれかを指定でき、出力は自動的にパースされバリデーションされます。これにより、下流のコードが安全に構造化データを扱えるようになります。`output_type` を設定すると、エージェントのファイナル出力はテキストではなく指定した型のオブジェクトになります。 🛠 使い方 `BaseModel` を継承した `CalendarEvent` クラスに `name: str`, `date: str`, `participants: list[str]` フィールドを定義し、`Agent` の `output_type=CalendarEvent` に指定します。` ...)` の ` が `CalendarEvent` 型として返され、` や `event.participants` で型安全にアクセスできます。 🏗 実践的な使い方 **メールからカレンダーイベントを抽出して API 登録** 構造化出力をそのまま外部 API に渡すパイプラインです。 ` email_body)` で抽出した ` を `CalendarEvent` 型として受け取り、`calendar_api.create_event(title= date= attendees=event.participants)` でそのまま外部 API に渡します。 **Enum 出力による分岐オーケストレーション** 分類結果を enum で返し、コードで確実に分岐させるパターンです。 `TicketCategory(str, Enum)` で `billing`, `technical`, `general` を定義し、`Classification(BaseModel)` に `category: TicketCategory` と `confidence: float` を持たせます。`Agent` の `output_type=Classification` を設定して分類を実行し、` を `match` 文で分岐して `handoff_to_billing`, `handoff_to_engineering`, `handoff_to_general` にルーティングします。 **ビジネスクリティカルな処理での型保証** 「壊れた JSON は絶対に許容できない」業務で、Structured Outputs が安全弁として機能します。 `InvoiceData(BaseModel)` に `invoice_number: str`, `amount: float`, `currency: str`, `due_date: str`, `line_items: list[dict[str, str | float]]` を定義し、`Agent` の `output_type=InvoiceData` に指定することで、請求書データの構造化抽出を型安全に保証します。 💡 ユースケース 📧 メールから CalendarEvent(name, date, participants) を抽出し、カレンダー API に自動登録 🏷 サポートチケットを Enum 分類し、category に応じてコードで確実にルーティング 💰 請求書・契約書の構造化抽出で「壊れた JSON が許されない」業務処理を型安全に 📊 アンケート自由記述を構造化データに変換し、集計パイプラインに直接投入 ⚠️ 注意点 - output_type を指定すると、エージェントの最終出力は必ずその型になります。通常のテキスト応答は返せなくなるため、テキスト応答が必要な場合は output_type を設定しないでください。 - 複雑すぎるネスト構造は LLM の出力精度を下げる可能性があります。できるだけフラットな構造を心がけましょう。 - Optional フィールドを適切に使い、LLM が情報を見つけられなかった場合の None を許容する設計にしましょう。 ✨ output_type を活用すれば、LLM の出力をそのままビジネスロジックに組み込めます。「パースして祈る」から「型で保証する」へ、一歩進んだエージェント開発を始めましょう！ #OpenAIAgentSDK# #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の便利だけど知られていない機能 🌍 エージェントのツール実行が遅い？読み取り専用ツールを並列化すれば大幅に高速化できます！ readOnlyHint を設定するだけで、安全なツールが自動的に並列実行されるようになります。 📌 タイトル：読み取り専用ツールの並列実行 (readOnlyHint) 🔗 URL： 🧩 概要 Claude Agent SDKでは、読み取り専用のツール（Read、Glob、Grep、および `readOnlyHint` が設定されたMCPツール）が自動的に並列実行されます。一方、書き込みを伴うツール（Edit、Write、Bash）は安全のため逐次実行されます。カスタムツールはデフォルトで逐次実行ですが、MCP SDKのアノテーションで `readOnlyHint` を設定することで並列実行の対象にできます。 🛠 使い方 ```typescript // MCP ツール定義で readOnlyHint を設定 const tool = { name: "search_database", description: "Search the database for records", inputSchema: { /* ... */ }, annotations: { readOnlyHint: true, // これで並列実行の対象になる }, }; ``` ```python # Python - MCP サーバーでのツール定義 @server.tool( name="search_database", annotations={"readOnlyHint": True}, ) async def search_database(query: str) -> str: # 読み取り専用の処理 return results ``` 🏗 本番システムへの組み込み方 ・データベース検索や外部API参照など、副作用のないカスタムツールには必ず `readOnlyHint` を設定します ・書き込みを伴うツールは逐次実行のままにして、データの整合性を保ちます ・並列実行による速度向上を計測し、ボトルネックを特定します ・MCP サーバーの設計段階で、読み取り専用と書き込みツールを明確に分離します 💡 ユースケース 🔍 複数のファイルを同時に検索して、コードベース全体の調査を高速化する 📊 複数のデータソースから同時にデータを取得して、分析レポートを素早く作成する 🌐 複数の外部APIを並列で呼び出して、情報収集のレイテンシーを削減する ⚠️ 注意点 ・`readOnlyHint` はあくまでヒントであり、ツールが実際に副作用を持たないことは開発者が保証する必要があります ・副作用のあるツールに誤って `readOnlyHint` を設定すると、並列実行による競合が発生する可能性があります ・カスタムツールはデフォルトで逐次実行のため、明示的に設定しないと並列化されません ・フィールド名は MCP SDK の仕様に由来しています ✨ ちょっとした設定一つで、エージェントの実行速度が劇的に変わることがあります。読み取り専用ツールへの `readOnlyHint` 設定は、最もコスパの良い最適化の一つです！ #ClaudeAgentSDK# #AIAgent#