便利だけど知られていないClaude APIの機能 🔒 ツールの引数が時々スキーマと合わない...そんな不安を仕組みで解消しませんか？ ClaudeのStrict Tool Use（厳密なツール使用）は、ツール定義にstrict: trueを付けることで、ツール呼び出しが常にスキーマと正確に一致することを保証する機能です。引数の型ズレや必須フィールドの欠落を構造的に防げます。 📌 タイトル：Strict Tool Use（厳密なツール使用） 🔗 URL： 🧩 概要 モデルがツールを呼び出すとき、引数がスキーマと一致しないことがまれに発生します。必須フィールドの欠落、型の不一致、余分なフィールドの追加など。Strict Tool Useを有効にすると、モデルの出力がツール定義のJSONスキーマに厳密に制約されます。不正な引数は構造的に生成されなくなるため、バリデーションコードを大幅に簡略化できます。 🛠 使い方 ツール定義のトップレベルにstrict: trueを追加するだけ。ただしスキーマはサポートされるJSON Schemaのサブセットに収める必要があり、オブジェクトには`additionalProperties: false`が必須です（`minimum`や`maxLength`などの制約は非対応で、使うと400エラーになります）。有効にすると、モデルはスキーマに完全に準拠した引数のみを生成します。型や必須フィールドの検証コードを省略でき、ツール実行側のエラーハンドリングがシンプルになります。 🏗 本番システムへの組み込み方 ・エージェントのツール基盤：全ツールにstrict: trueを付けて、引数不正によるランタイムエラーを根絶。デバッグ時間が大幅に減ります。 ・外部API連携：ツール引数をそのまま外部APIのリクエストボディとして使う場合、スキーマ準拠が保証されていれば安全にそのまま渡せます。 ・マルチステップパイプライン：ステップ間のデータ受け渡しにツールを使う構成で、型安全なデータフローを確保。 ・バリデーションコスト削減：引数の検証ロジックを削除または簡略化でき、コードのメンテナンスコストが下がります。 💡 ユースケース 🤖 エージェントのツール引数の品質保証 🔌 外部APIへの安全な引数パススルー 🔗 ステップ間の型安全なデータ受け渡し 🧹 バリデーションコードの削減 ⚠️ 注意点 strictモードはスキーマをコンパイルした文法で出力を制約するため、あるスキーマを初めて使うリクエストではコンパイル分のレイテンシが増えます（コンパイル結果は最終使用から24時間キャッシュされます）。複雑さには明示的な上限があり、1リクエストあたり厳密なツールは20個、オプションパラメータは合計24個、union型を持つパラメータは合計16個までで、超えると400エラーになります。シンプルなスキーマで使うのが最も効果的です。 ✨ 「引数が壊れてないか祈る」コードはもう要りません。strict: trueの一行で、ツール呼び出しの信頼性が格段に上がります。 #Claude# #LLM#

# Claude Agent SDKの便利だけど知られていない機能 🌍 @tool デコレータと create_sdk_mcp_server で、独自の関数をエージェントのツールとしてインプロセスで実行できます。 データベースアクセス、外部API呼び出し、ドメイン固有のロジックをエージェントに提供する方法を解説します。 📌 タイトル：インプロセス・カスタムツール (create_sdk_mcp_server / @tool) 🔗 URL： 🧩 概要 カスタムツールは、SDK のインプロセス MCP サーバーを使って独自の関数を Claude から呼び出せるようにする機能です。Python では `@tool` デコレータ、TypeScript では `tool()` ヘルパーでツールを定義し、`create_sdk_mcp_server` でラップして `query()` に渡します。ツールはアプリケーションプロセス内で実行され、別プロセスは不要です。ツール名は `mcp__{server_name}__{tool_name}` の形式になります。`readOnlyHint` アノテーションで並列実行を有効にし、`isError` で復旧可能なエラーをエージェントに伝え、画像（base64）やリソースの返却も可能です。 🛠 使い方 `@tool` デコレータでツールを定義し、`create_sdk_mcp_server` でサーバーにまとめます。 ```python from typing import Any import httpx from claude_agent_sdk import tool, create_sdk_mcp_server, query, ClaudeAgentOptions, ResultMessage @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, ) async def get_temperature(args: dict[str, Any]) -> dict[str, Any]: async with httpx.AsyncClient() as client: response = await client.get( "", params={ "latitude": args["latitude"], "longitude": args["longitude"], "current": "temperature_2m", }, ) data = response.json() return { "content": [ {"type": "text", "text": f"Temperature: {data['current']['temperature_2m']}"} ] } # インプロセスMCPサーバーにラップ weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature], ) # query() に渡して使用 async for message in query( prompt="What's the temperature in Tokyo?", options=ClaudeAgentOptions( mcp_servers={"weather": weather_server}, allowed_tools=["mcp__weather__get_temperature"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` 🏗 本番システムへの組み込み方 ・エラーハンドリングでは例外をスローせず `{"is_error": True}` を返すことで、エージェントループを継続させつつ Claude にリカバリーさせることができます ・`readOnlyHint=True` アノテーションを設定すると、副作用のないツールを他のリードオンリーツールと並列実行できます ・画像を返す場合は `{"type": "image", "data": base64_str, "mimeType": "image/png"}` 形式のコンテンツブロックを使用します ・`structuredContent` フィールドでツール結果を機械可読な JSON として返却できます（ただし Python の `@tool` では未サポート、スタンドアロン MCP サーバーが必要） 💡 ユースケース 🗄 データベースアクセス：エージェントに直接 DB クエリを実行させる 🌐 外部API連携：社内 API やサードパーティサービスをツールとして公開する 📊 データ可視化：グラフを生成し画像（base64）として返却する 🔧 ドメインロジック：計算、変換、バリデーションなど特定の業務ロジックをツール化する ⚠️ 注意点 ・Python の dict スキーマではすべてのキーが必須になります。オプションパラメータは schema に含めず、description で説明して `args.get()` で読み取ってください ・`structuredContent` は Python の `@tool` デコレータでは転送されません（スタンドアロン MCP サーバーを使用） ・ツール検索（tool search）はデフォルトで有効で、SDK MCP ツールのスキーマは必要になるまで遅延ロードされます。無効にすると `tools` 配列のすべてのツールが毎ターンのコンテキストを消費します ・アノテーションはメタデータであり強制力はありません。`readOnlyHint=True` でも handler が書き込みを行う場合があります ✨ インプロセスのカスタムツールにより、エージェントの能力を自由に拡張でき、外部プロセスの管理も不要です。 #ClaudeAgentSDK# #AIAgent#

AIエージェントをエンタープライズシステムに組み込むプラクティス 【MCPゲートウェイ / ツール・フェデレーション（MCP Gateway）】 💡 「エージェント5つ × SaaS 10種 = 50本の個別統合。この掛け算地獄を解消するのがMCPゲートウェイです。」 エージェントが増え、接続先SaaSが増えるたびに統合コストが爆発します。ツール定義の乱立、スキーマの不整合、そしてSaaSのサイレント仕様変更による暗黙の破綻。これらをアーキテクチャレベルで解決します。 🔥 解決する課題 - N（エージェント）×M（SaaS）の統合コスト爆発 - 各エージェントが独自にツール定義を持つことによる重複・不整合 - ツール経由の間接プロンプトインジェクション - エージェントに見えるツールが多すぎることによる選択精度の劣化 - SaaSのサイレント仕様変更（APIレスポンス形式変更等）による暗黙の破綻 🏗️ 提案パターン 各SaaSコネクタをMCP（Model Context Protocol）サーバとして束ね、ゲートウェイがツールの発見・認可・呼び出し監査・スコープ制御を一元管理します。ツール許可リストを主体（部署×エージェント種別）で動的に絞り、エージェントに見えるツールを必要最小限にします。危険ツール（削除・送金・外部送信など不可逆操作）には承認フックを設置します。さらに、ツール定義/APIスキーマを「契約」としてバージョン管理し、定期的に実APIと突合してドリフト（乖離）を検知します。後方互換のないドリフトを検出した場合は、アラート＋該当ツールの一時無効化で安全側に倒します。 ✅ 選定条件 - 採用する場合：連携SaaSが10種以上。複数エージェントが共通ツールを使う。N×M統合の複雑さに困っている。 - 採用しない場合：ツールが2〜3個固定の単機能エージェント（直結のほうが堅牢でシンプル）。依存APIが安定していて変更頻度が極めて低い環境。 ⚠️ 落とし穴 - エージェントに露出するツールが20〜30を超えると選択精度が低下します。tool RAGで意図に応じて動的に絞るか、役割別サブエージェントに分割してください。 - 契約テスト（ドリフト検知）を導入しないと、SaaS側の仕様変更に気づかず、エージェントが誤ったデータを処理し続けます。Salesforce APIのフィールド変更などは実際に起きる頻度が高いです。 - MCPサーバの認可設計を後回しにすると、全エージェントが全ツールにアクセスできる状態が放置されます。 🛠️ 実装方針 - 各SaaS（Salesforce / ServiceNow / Jira / Slack / Box 等）のMCPサーバを構築します。公式MCPサーバがあればそれを採用し、なければOpenAPI定義からツールを自動生成して自作MCPサーバとして用意します。 - MCPゲートウェイを配置し、ツールレジストリ（カタログ）を構築します。各MCPサーバが提供するツールを一覧化し、部署×エージェント種別でアクセス可能なツールを動的にフィルタリングする許可リストを設定します。 - OAuth 2.1 ベースの認可と承認フックを設定します。不可逆操作（削除・送金・外部送信）を行うツールにはP09（動的認可PDP）と連携した承認ゲートを設置し、人間の承認なしに実行されない構成にします。 - 契約テスト（Pact等）とスキーマレジストリでドリフト検知パイプラインを構築します。週次でツール定義と実APIスキーマを突合し、後方互換のない変更を検出した場合はアラート＋該当ツールの自動無効化を行います。 - tool RAG または役割別サブエージェント分割で、各エージェントに露出するツール数を20以下に制御します。意図に応じて動的にツールを絞り込み、選択精度を維持します。 #AIエージェント# #エンタープライズアーキテクチャ#

AIエージェントをエンタープライズシステムに組み込むプラクティス 【MCPゲートウェイ / ツール・フェデレーション（MCP Gateway）】 💡 ポイント 「エージェント5つ × SaaS 10種 = 50本の個別統合。この掛け算地獄を解消するのがMCPゲートウェイです。」 エージェントが増え、接続先SaaSが増えるたびに統合コストが爆発します。ツール定義の乱立、スキーマの不整合、そしてSaaSのサイレント仕様変更による暗黙の破綻。これらをアーキテクチャレベルで解決します。 🔥 解決する課題 - N（エージェント）×M（SaaS）の統合コスト爆発 - 各エージェントが独自にツール定義を持つことによる重複・不整合 - ツール経由の間接プロンプトインジェクション - エージェントに見えるツールが多すぎることによる選択精度の劣化 - SaaSのサイレント仕様変更（APIレスポンス形式変更等）による暗黙の破綻 🏗️ 提案パターン 各SaaSコネクタをMCP（Model Context Protocol）サーバとして束ね、ゲートウェイがツールの発見・認可・呼び出し監査・スコープ制御を一元管理します。ツール許可リストを主体（部署×エージェント種別）で動的に絞り、エージェントに見えるツールを必要最小限にします。危険ツール（削除・送金・外部送信など不可逆操作）には承認フックを設置します。さらに、ツール定義/APIスキーマを「契約」としてバージョン管理し、定期的に実APIと突合してドリフト（乖離）を検知します。後方互換のないドリフトを検出した場合は、アラート＋該当ツールの一時無効化で安全側に倒します。 ✅ 選定条件 - 採用する場合：連携SaaSが10種以上。複数エージェントが共通ツールを使う。N×M統合の複雑さに困っている。 - 採用しない場合：ツールが2〜3個固定の単機能エージェント（直結のほうが堅牢でシンプル）。依存APIが安定していて変更頻度が極めて低い環境。 ⚠️ 落とし穴 - エージェントに露出するツールが20〜30を超えると選択精度が低下します。tool RAGで意図に応じて動的に絞るか、役割別サブエージェントに分割してください。 - 契約テスト（ドリフト検知）を導入しないと、SaaS側の仕様変更に気づかず、エージェントが誤ったデータを処理し続けます。Salesforce APIのフィールド変更などは実際に起きる頻度が高いです。 - MCPサーバの認可設計を後回しにすると、全エージェントが全ツールにアクセスできる状態が放置されます。 🛠️ 実装方針 - 各SaaS（Salesforce / ServiceNow / Jira / Slack / Box 等）のMCPサーバを構築します。公式MCPサーバがあればそれを採用し、なければOpenAPI定義からツールを自動生成して自作MCPサーバとして用意します。 - MCPゲートウェイを配置し、ツールレジストリ（カタログ）を構築します。各MCPサーバが提供するツールを一覧化し、部署×エージェント種別でアクセス可能なツールを動的にフィルタリングする許可リストを設定します。 - OAuth 2.1 ベースの認可と承認フックを設定します。不可逆操作（削除・送金・外部送信）を行うツールにはP09（動的認可PDP）と連携した承認ゲートを設置し、人間の承認なしに実行されない構成にします。 - 契約テスト（Pact等）とスキーマレジストリでドリフト検知パイプラインを構築します。週次でツール定義と実APIスキーマを突合し、後方互換のない変更を検出した場合はアラート＋該当ツールの自動無効化を行います。 - tool RAG または役割別サブエージェント分割で、各エージェントに露出するツール数を20以下に制御します。意図に応じて動的にツールを絞り込み、選択精度を維持します。 #AIエージェント# #エンタープライズアーキテクチャ#

# OpenCodeの機能と実践的な使い方 ⚡ OpenCodeはTUIだけのツールではありません。`opencode run` を使えば非対話でプロンプトを実行でき、シェルスクリプトやCIパイプラインにAIを直接組み込めます。 🏷️ タイトル: プログラマティック実行 🔗 URL: 📘 概要 OpenCodeのCLIは、既定ではTUIを起動しますが、コマンドとフラグを通じてプログラマティックに動かせます。中心となるのが、プロンプトを一発で実行する `opencode run` です。 ⚙️ 機能の説明 ・`opencode run "..."`: 非対話でプロンプトを実行します。主なフラグは `-m/--model`（`provider/model` 指定）、`--agent`（カスタムエージェント）、`-s/--session`（既存セッション継続）、`-c/--continue`（直近セッション再開）、`-f/--file`（ファイル添付）、`--format`（`json` 等で出力）、`--attach`（起動中サーバーへ接続）です。 ・`serve`: UIなしのヘッドレスAPIサーバーを起動します（`--port`、認証は `OPENCODE_SERVER_PASSWORD`）。 ・`session`: 会話履歴の一覧・削除（`session list --format json`、`session delete `）。 ・`export` / `import`: セッションの書き出し・取り込み（`export --sanitize`）。 ・`models` / `auth` / `agent` / `github` / `mcp` / `stats` / `upgrade`: モデル一覧、認証管理、エージェント作成、GitHub連携、MCP管理、利用量確認、更新。 🛠️ 実践的な使い方 非対話実行をスクリプトに組み込めば、複数ファイルの一括処理やCIでのレビューが自動化できます。例えば `opencode run --format json "この差分をレビューして"` の出力をファイルに保存したり、`opencode serve` を常駐させて各ファイルを `opencode run --attach ... --file` でループ処理したりでき、`--attach` で接続するとレイテンシを抑えられます。 💡 ユースケース CIで変更ファイルだけを `opencode run` に渡してレビューコメントをJSONで受け取り、後続ジョブで集計・通知する、といった機械処理に向きます。`stats` で日次のトークン消費とコストを監視するのも有効です。 ⚠️ 注意点 ・`serve` を外部公開する際は `OPENCODE_SERVER_PASSWORD` による認証を必ず設定してください。 ・`--format json` の出力構造に依存する処理は、バージョン更新時に必ず確認しましょう。 ・`OPENCODE_DISABLE_AUTOUPDATE` などの環境変数で、CI環境での自動更新を抑止できます。 #OpenCode# #CLI#

# Codexの機能と実践的な使い方 🚀 「コードを書くすべての場所に、ひとつのエージェントを」。OpenAI Codexは、生成から理解・レビュー・デバッグまでを丸ごと任せられるAIコーディングエージェントです。 🏷️ タイトル: Codex 基礎 🔗 URL: 📘 概要 Codexは、ソフトウェア開発のためにOpenAIが提供するAIコーディングエージェントです。単なるコード補完ではなく、既存のプロジェクト構成や規約を読み取りながら、自律的にタスクを進めてくれます。ChatGPTのPlus/Pro/Business/Edu/Enterpriseプランに組み込まれています。 ⚙️ 機能の説明 Codexの中心となる能力は大きく5つです。 ・コード生成: 「何を作りたいか」を伝えると、既存の構成や命名規約に合わせてコードを書きます。 ・コードベース理解: 複雑なコードやレガシーコードを読み解き、システムの構造を説明します。 ・コードレビュー: バグ・ロジックの誤り・未処理のエッジケースを洗い出します。 ・デバッグ: 失敗を追跡し、根本原因を診断して、的を絞った修正を提案します。 ・反復作業の自動化: リファクタリング・テスト・マイグレーション・セットアップを代行します。 これらを安全に動かすために、サンドボックスによる実行境界と承認ポリシーという仕組みが土台にあります。 🛠️ 実践的な使い方 Codexは「コードを書くあらゆる場所」で動くのが特徴で、複数の入口が用意されています。 ・CLI: ターミナルで `codex` を起動して対話的に作業 ・IDE拡張: エディタ内からそのまま委任 ・Web / クラウド: ローカルに無いリポジトリのタスクを並列実行 ・GitHub連携: PRに `@/codex review` でレビューを依頼 ・Slack連携: スレッドで `@/codex` にメンションしてタスク起動 まずはCLIで `npm i -g @/openai/codex` から始め、慣れてきたらGitHubやSlackに広げるのが王道です。 💡 ユースケース 未知のリポジトリに参加した初日に「このプロジェクトについて教えて」と尋ねて全体像をつかむ、レビュー前にバグを先に潰してもらう、退屈な一括リファクタリングを丸ごと委任する、といった使い方が現実的です。人間は方針決定とレビューに集中できます。 ⚠️ 注意点 Codexはファイルの読み書きやコマンド実行を伴う自律エージェントです。タスクの前後でGitのチェックポイント（コミット）を作っておくと、いつでも安全に巻き戻せます。認証はChatGPTアカウントが推奨で、APIキー認証では一部機能が制限される場合があります。 #OpenAICodex# #AIコーディング#

# AIエージェントをエンタープライズシステムに組み込む意思決定ポイント # Pull vs Push｜エージェントの起動モデル 🎯 ポイント エージェントを「ユーザーが呼んだら動く」だけの設計にしていませんか？実はエージェントの起動トリガには、ユーザーの明示的な要求で動くPull型と、システムイベントで自動起動するPush型の2つがあります。どちらを選ぶかでユーザー体験・負荷特性・権限モデルが根本的に変わります。多くの本番環境ではPullとPushの比率が7:3から5:5に落ち着くのが現実です🔑 📋 概要 Pull型はユーザーが意図を持って質問や指示を出す対話型タスクに適しています。Slack Botへの問い合わせやSalesforceの商談画面からの指示がその典型です。Push型はシステムイベント（Webhook、CDC、スケジュール）をトリガに自動起動し、異常検知や予防的アクションを行います。JiraチケットのSLA超過を検知して自動エスカレーションしたり、夜間バッチで勤怠異常を検出して翌朝是正案を提示したりするケースです。エンタープライズでは両方を組み合わせるハイブリッド構成が一般的です📊 🔍 意思決定のポイント 判断の軸は3つあります。 まず、トリガが明確なシステムイベント（Webhook、CDC、cron）で定義できるかどうか。定義できるならPushを検討してください。 次に、ユーザーの意図やコンテキスト（選択中の画面、直前の操作）が実行に不可欠かどうか。不可欠ならPullを主軸にしましょう。 そして「ユーザーが気づく前に対処する」ことに価値があるかどうか。SLA違反の予防やインシデントの早期検知のように、先手を打つことで損失を防げるならPushが有効です。 両方に該当する場合は、Pushで通知してPullで深掘りするハイブリッド構成が最適解です。Pushを採用する場合は、イベント量の見積もりとスロットリングの設計を必ず行ってください⚡ 💡 要点と詳細 ハイブリッド構成の典型パターンを理解しておくことが重要です： Pushで気づかせ、Pullで深掘り — イベント駆動でサマリ通知を送り、ユーザーが詳細を知りたければ対話に移行します。Zendeskで顧客満足度が急落した際にアラートを飛ばし、担当者が「原因を分析して」と指示する流れです。 Pullの裏でPushを仕込む — ユーザーの問い合わせ対応中に、関連するイベント（同じ顧客の未解決チケット）をバックグラウンドで監視し、追加情報をプロアクティブに提示します。 Push型では権限設計に特に注意が必要です。Pull型はリクエスト発行者のセッションに権限が紐づくため認可モデルがシンプルですが、Push型はユーザーセッションに紐づかないため、どの権限でAPIを叩くかを明確にしないと過剰権限のサービスアカウントを使ってしまうリスクがあります🔄 ⚖️ トレードオフ Push過多は通知疲れを引き起こします。イベントの閾値を適切に設定しないと大量のアラートがユーザーに押し寄せ、Slackチャンネルが未読通知で埋まって結局すべて無視されます。通知の価値がゼロになるだけでなく、本当に重要なアラートも見落とされます😰 一方、Pullのみで運用すると予防機会を逃します。異常を検知できるイベントソースがあるのにPullだけに頼ると、ユーザーが気づいた時にはSLA違反が確定しています。「気づいてからでは遅い」タイプの問題には、Pushが不可欠です。 もう一つの落とし穴はイベントストームです。デプロイ直後やシステム移行時に大量のCDCイベントが発生し、Pushエージェントがバックログを処理しきれずタイムアウトが連鎖する事態は、事前のスロットリング設計で防ぐ必要があります⚠️ 🛠️ ユースケース インシデント対応エージェント（ServiceNow連携）：Push型でP1インシデントの昇格を即座に検知し、オンコール担当への通知と初期分析を自動送信。担当者がPull型で「影響範囲を詳しく分析して」と指示すると、関連システムのログを横断的に調査して報告します。Pushで初動を高速化し、Pullで深掘りするハイブリッドの好例です🏢 勤怠管理エージェント（Workday連携）：夜間バッチのPush型で勤怠異常（残業超過、打刻漏れ）を検出し、翌朝マネージャーに是正案を提示。マネージャーがPull型で「この部門の先月の傾向は？」と質問すると、詳細な分析レポートを生成します📚 営業支援エージェント（Salesforce連携）：商談のステージ変更をPush型で監視し、長期間滞留している案件を自動で営業担当にリマインド。担当者がPull型で「この顧客の過去のサポート履歴をまとめて」と指示すると、Zendeskの対応履歴も含めた総合レポートを生成します🔧 実践のコツ：Push型を導入する際は「通知の閾値設計」から始めてください。全イベントを通知するのではなく、ビジネスインパクトのあるイベントだけを選別する仕組みが必須です。また、Pushエージェントのサービスアカウント権限は最小権限の原則を徹底しましょう💪 #AIエージェント# #エンタープライズアーキテクチャ#

API経由での攻撃ってこういう経路か、、、 （a）一般公開しているスマートフォンアプリを解析しAPIのエンドポイントやキーを特定する