# AIエージェントをソフトウェアに組み込むプラクティス # Verified Structured Output｜検証済み構造化出力 🎯 LLMの出力をそのまま下流システムに流していませんか？JSONが壊れている、値が不正、フィールドが足りない――「黙って壊れる」を防ぐのがこのパターンです。 🔥 解決する課題 LLMの出力は本質的に曖昧な自然言語です。下流のコードやAPIが期待する型やフィールドに従わない出力が返ると、パース失敗・型エラー・無効な値の混入がサイレントに後続処理を破壊します。フォーマットが正しくても「過去の日付を未来として返す」「存在しない商品IDを含める」といったビジネスルール違反は、構文チェックだけでは検出できません。 💡 提案パターン LLMの出力をresponse_formatやfunction_callingでJSON Schemaに準拠させる第1層（スキーマ検証）と、決定論的コードでビジネスルール制約を検証する第2層（意味的検証）の二段構成にします。違反時はエラー内容をコンテキストに追加して自己修正リトライを行い、予算内（目安1-3回）で収束しなければfail-fastします。温度は0.0-0.3に設定し、構造化出力の従順率を確保します。 ✅ 選定条件 使うとき： - LLMの出力を下流のコード・API・データベースが消費する - 出力が従うべきスキーマ（型・必須フィールド・値域）が定義可能 - 不正な出力が後続処理を壊すと業務影響がある 使わないとき： - 出力が自由形式のテキスト（要約・対話）で構造化の必要がない - 出力スキーマが頻繁に変わりスキーマ維持コストが利益を上回る - 不正出力をそのまま捨てても問題ない低リスク用途 ⚠️ 落とし穴 - リトライ時にエラーメッセージを毎回追加するとトークン消費が膨らみます。直前のエラーだけを渡すか要約する工夫が必要です - スキーマのフィールド数が多すぎると（概ね15超）LLMの従順率が下がります。大きいスキーマは分割呼び出しを検討してください - response_formatはプロバイダ依存です。スキーマ定義はPydanticやJSON Schemaなど中間表現で管理してください 🔧 実装方針 - 第1層（スキーマ検証）ではresponse_formatやfunction_callingでJSON Schemaに準拠させ、Pydanticモデルで型・値域を強制します - 第2層（ビジネスルール検証）では決定論的コードで日付範囲・ID存在・権限等のドメイン制約を検証します - 検証失敗時はエラー内容をコンテキストに追加して自己修正リトライを行い、予算（目安1-3回）で打ち切りfail-fastします - LLMの温度は0.0-0.3に設定し、構造化出力の従順率を確保します - スキーマ定義はPydanticやJSON Schemaなどプロバイダ非依存の中間表現で管理し、移植性を担保します #AIエージェント# #ソフトウェアアーキテクチャ#

自閉症では社会的ルールを自然に学ぶことが難しい場合があります。そのため明示的な説明や構造化が必要になります。#自閉症スペクトラム# #社会認知#

【ポケモン】『ポケットモンスター』複雑化するバトルを支えるシステム設計と運用事例。カギとなるのは構造化と拡張性【CEDEC2026】 1000種を超えるポケモン、900以上の技、300種を上回る特性が複雑に絡み合うバトルを処理するシステム、肝となる構造化と拡張性の確保を解説

# Claude Agent SDKの便利だけど知られていない機能 🌍 複雑なタスクの進捗、見失っていませんか？構造化タスクトラッキングで可視化できます！ Claude Agent SDKには、エージェント実行中のタスク管理と進捗表示を行う組み込み機能があります。 📌 タイトル：構造化タスク(Todo)トラッキング 🔗 URL： 🧩 概要 `TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList` の4つのツールを使って、エージェント実行中の構造化タスク管理が可能です。これらのタスクトラッキングツールは Claude 3.x 系、Opus 4〜4.7、Sonnet 4〜4.6、Haiku 4.5 でのみデフォルトで提供され（Claude Code v2.1.268 以降、TypeScript SDK は v0.3.268 以降がこの既定を同梱）、それ以外のモデルではオプトインが必要です。エージェントは複数ステップの作業を自動的にタスクとして登録し、`pending` → `in_progress` → `completed` のライフサイクルで進捗を管理します。従来の `TodoWrite` は全リストを毎回上書きしていましたが、新しい Task ツールでは個別のタスク単位で作成・更新できるため、より細かい進捗追跡が実現できます。 🛠 使い方 ```python # Python - TaskCreate/TaskUpdate のストリームを監視 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock async for message in query( prompt="React アプリのパフォーマンスを最適化してください", # 既定で Task ツールが提供されないモデルでも有効化する options=ClaudeAgentOptions(env={"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}), ): if not isinstance(message, AssistantMessage): continue for block in message.content: if not isinstance(block, ToolUseBlock): continue if == "TaskCreate": print(f"+ {block.input['subject']}") elif == "TaskUpdate" and block.input.get("status"): # ストリーム上のキー名は修復前の生の形（id / task_id の場合がある） task_id = ( block.input.get("taskId") or block.input.get("id") or block.input.get("task_id") ) print(f" {task_id} -> {block.input['status']}") ``` ```typescript // TypeScript - タスクの作成と更新をリアルタイム表示 import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Optimize my React app performance", // 既定で Task ツールが提供されないモデルでも有効化する options: { env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } }, })) { if (message.type !== "assistant") continue; for (const block of message.message.content) { if (block.type !== "tool_use") continue; if ( === "TaskCreate") { console.log(`+ ${block.input.subject}`); } else if ( === "TaskUpdate") { // ストリーム上のキー名は修復前の生の形（id / task_id の場合がある） const taskId = block.input.taskId ?? ?? block.input.task_id; if (taskId && block.input.status) console.log(` ${taskId} -> ${block.input.status}`); } } } ``` 🏗 本番システムへの組み込み方 ・タスクの進捗をUIのプログレスバーやチェックリストに反映して、ユーザーに作業状況を可視化します ・`TaskCreate` の結果から `taskId` を取得し、マップで管理することで完全なタスク一覧を構築できます ・`TaskList` のツール結果を監視してスナップショットを取得し、ダッシュボードに表示します ・3ステップ以上の複雑なタスクで自動的にタスクが作成されるため、長時間実行の監視に活用できます 💡 ユースケース 📋 大規模リファクタリングの進捗をリアルタイムでチームに共有する 🔄 CI/CDパイプラインでエージェントの各ステップの完了状況を追跡する 📊 マルチステップのコード分析で、どの分析が完了したかをダッシュボードに表示する ⚠️ 注意点 ・`TaskCreate` の入力には `taskId` は含まれません。対応する `tool_result` ブロックから `{ task: { id, subject } }` として取得する必要があります ・既定でツールが提供されないモデルでは、`allowed_tools` にツール名を挙げる、`tools` オプションに列挙する、`env` で `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` を設定する、のいずれかでオプトインが必要です（オプトインしないと該当の `tool_use` ブロックはストリームに現れません）。逆に `CLAUDE_CODE_ENABLE_TASKS=0` を設定すると、4つの Task ツールの代わりに旧 `TodoWrite` が提供されます ・`status` を `"deleted"` に設定するとタスクを削除できます ✨ 複数ステップの作業を「何をやっているか分からない」状態で待つのはストレスフルです。タスクトラッキングを活用して、エージェントの作業をガラス張りにしましょう！ #ClaudeAgentSDK# #AIAgent#

AIエージェントをエンタープライズシステムに組み込むプラクティス 【オブザーバビリティ / トレース＋プロベナンス】 💡 「なぜその回答になったか」を説明できないエージェントは、本番に出してはいけません。構造化トレースとプロベナンスで、確率的な挙動を追跡可能にしましょう。 🔥 解決する課題 - 「なぜこの回答になったか」を再現・分析できない - 部署・プロジェクト・エージェント単位のコストを把握できない - モデル変更やプロンプト変更による品質劣化をサイレントに見逃す - 規制下の意思決定で「なぜこの判断になったか」を後から説明できない 🏗️ 提案パターン 推論ステップ・ツール呼び出し・トークン数・コスト・レイテンシ・評価スコアをOpenTelemetry準拠の構造化トレースで記録します。ログ基盤にはメタデータを、オブジェクトストレージにはプロンプト本文や生出力を格納し、トレースIDで紐付けます。正常系はサンプリング（1〜10%が起点）、エラーや低評価は全量記録します。規制下の重要な意思決定には、参照データ・推論経路・使用モデル・承認者まで遡れるプロベナンス（来歴）を追加します。 ✅ 選定条件 - 向き：本番運用するすべてのエージェント（例外なし） - 不向き：特になし（本番では必須パターン） ⚠️ 落とし穴 - 全プロンプト本文をログ基盤に入れると容量・コストが非現実的になる - PIIのマスキングを怠るとトレースログ自体がセキュリティリスクになる - プロベナンスの粒度を決める設計判断は、必ず人間のレビューを通すべき 🛠️ 実装方針 1. OpenTelemetry GenAI semantic conventions 準拠のスパンを全エージェントに組み込み、推論・ツール呼び出し・検索の各ステップをトレースIDで一貫して記録します 2. Langfuse / LangSmith / Arize 等のLLMオブザーバビリティ基盤にメタデータ（モデル名・トークン数・レイテンシ・コスト・評価スコア）を送信し、ダッシュボードで部署別コスト・品質推移を監視します 3. プロンプト本文・コンテキスト・生出力はオブジェクトストレージ（S3等）に格納し、ログ基盤のメタデータとIDで紐付けます 4. tail-based sampling を導入し、正常系は1〜10%サンプリング、エラー・低評価・高コストのリクエストは全量記録します 5. 規制対応が必要な場合は、決定ログをappend-onlyの不変監査ログとして保持し、参照データ・使用モデル・プロンプトバージョン・承認者まで逆引き可能なプロベナンスを構築します #AIエージェント# #エンタープライズアーキテクチャ#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 エージェント間の引き継ぎで、理由やメタデータも一緒に渡したいことはありませんか？ Handoff inputsとon_handoffを使えば、構造化されたデータとともにスムーズな引き継ぎが実現できます。 📌 タイトル：Handoffs – Handoff inputs 🔗 URL： 🧩 概要 Handoff inputsは、handoff時にモデルが生成する構造化データを引き継ぎ先エージェントに渡す仕組みです。`on_handoff`コールバックと組み合わせることで、引き継ぎ理由のログ記録、メタデータの事前取得、引き継ぎ先エージェントへのコンテキスト注入が可能になります。 🛠 使い方 Pydanticモデル `EscalationData(BaseModel)` で `reason: str`, `priority: str = "normal"`, `customer_tier: str = "standard"` を定義し、handoff時の構造化データとします。`on_escalation(ctx: RunContext, input_data: EscalationData)` コールバックでは、`input_data.reason` や `input_data.priority` をログ出力し、`ctx.context["customer_id"]` から顧客データを事前取得して `ctx.context["customer_data"]` に格納します。エスカレーション先の `Agent(name="escalation", instructions="...")` と、トリアージ用の `Agent(name="triage", handoffs=[Handoff(agent=escalation_agent, input_type=EscalationData, on_handoff=on_escalation, handoff_description="複雑な問い合わせや緊急対応が必要な場合")])` を定義します。`await input="二重請求されました。すぐに対応してほしいです。", context={"customer_id": "C-12345"})` で実行します。 🏗 実践的な使い方 **エスカレーション理由の構造化** `EscalationData(reason, priority)`のようにPydanticモデルで引き継ぎ理由を型安全に定義できます。モデルが自由文で理由を生成するのではなく、構造化されたデータとして受け取れるため、後続処理やログ分析が容易になります。 **on_handoffでのデータ事前取得** `on_handoff`コールバック内で、引き継ぎ先エージェントが必要とするデータをDBやAPIから事前に取得できます。これにより、引き継ぎ先エージェントが改めてデータ取得ツールを呼ぶ必要がなくなり、レイテンシを削減できます。 **メタデータの伝達** 返金エージェントに`{"reason": "duplicate_charge", "priority": "high"}`を渡すことで、返金ポリシーの判断に必要な情報を構造化された形で引き継げます。自由文の会話履歴からモデルが推測するよりも正確です。 **監査ログの記録** `on_handoff`内で引き継ぎの理由・タイミング・優先度を監査ログに記録できます。カスタマーサポートのSLA管理や、エスカレーション傾向の分析に活用できます。 💡 ユースケース 🔄 カスタマーサポートのエスカレーション（理由と優先度を構造化して引き継ぎ） 💳 返金処理への引き継ぎ（二重請求/商品不良/キャンセルなどの理由を明示） 📊 引き継ぎ理由の集計・分析（on_handoffでログ記録→ダッシュボード化） ⚡ 引き継ぎ先エージェントのレイテンシ削減（on_handoffでデータプリフェッチ） ⚠️ 注意点 - `input_type`に指定したPydanticモデルのフィールドが多すぎると、モデルが正確にデータを生成できなくなります。必須フィールドは最小限にし、オプショナルフィールドにはデフォルト値を設定してください。 - `on_handoff`内で例外が発生するとhandoff全体が失敗します。外部API呼び出しにはtry-exceptを入れ、フォールバック処理を用意してください。 - `on_handoff`は同期的に実行されます。重い処理を入れるとhandoffのレイテンシが増加するため、必要最小限の処理に留めてください。 - `input_type`を指定しない場合、`on_handoff`のコールバックは`input_data`引数を受け取りません。 ✨ Handoff inputsで構造化されたコンテキストを引き継ぎ、エージェント間の連携をスムーズにしましょう！ #OpenAIAgentSDK# #AIAgent#

# AIエージェント開発の意思決定ポイント # 温度（Temperature） 🎯 ポイント 温度パラメータ、全部のタスクに同じ値を設定していませんか？ エージェントシステムにおける温度は「創造性のつまみ」ではありません。構造化出力、ツール呼び出し、ユーザー応答 -- 経路ごとに最適な温度は全く違います。1つのエージェント内でも使い分けるのが基本です。 📋 概要 温度はLLMが次のトークンを選ぶ際の確率分布の「尖り具合」を制御するパラメータです。温度0に近いほど最も確率の高いトークンが選ばれやすくなり、出力は決定論的で安定します。温度を上げると確率分布が平坦化し、低確率のトークンも選ばれるようになるため、出力の多様性と創造性が増します。 AIエージェントでは、構造化出力を生成する場面、ツール呼び出しの引数を組み立てる場面、自由形式のテキストを生成する場面で求められる温度が異なります。温度は単一の固定値ではなく、タスクの種別に応じて動的に切り替えるべき変数です。 🔍 意思決定のポイント 温度の設定は主にtask_variability（タスクの定型度）で決まります。判定フローは明快です 🧭 1. 構造化出力（JSON/関数呼び出し）か？ → 0.0〜0.3 2. 正確性が最優先（事実抽出・分類・要約）か？ → 0.2〜0.5 3. 対話・説明・コミュニケーションか？ → 0.5〜0.7 4. 創作・ブレインストーミング・候補生成か？ → 0.7〜1.0 加えて、failure_cost（失敗コスト）が高いほど温度の上限を下げ、cost_sensitivity（コスト感度）が高い環境ではリトライによるコスト増を見込んで温度を抑えます。 💡 要点と詳細 タスク別の目安値 📊 - 構造化出力（JSON / function calling） → 0.0〜0.3。スキーマ違反の最小化が最優先 - 分類・抽出・データ変換 → 0.0〜0.2。正確性と再現性が命 - 要約・説明・カスタマー対応 → 0.5〜0.7。自然さと正確性のバランス - 創作・ブレスト・候補生成 → 0.7〜1.0。多様性が価値の源泉 - ツール引数の生成 → 0.0〜0.2。関数名・引数名の正確性が不可欠 - 計画・推論 → 0.3〜0.6。多少の探索は有益だが論理の一貫性を保つ 構造化出力の温度はまず0から始めてください。0でもスキーマ違反が出る場合はプロンプトかスキーマの問題です。温度を上げて「偶然正しい出力が出る」ことに依存してはいけません 🚫 ⚖️ トレードオフ 温度が低すぎると対話が機械的で紋切り型になります 🤖 同じ質問に毎回同じ回答を返し、「テンプレート応答」の印象を与えます。Best-of-Nサンプリングも候補がほぼ同一になり、N倍のコストだけかかって実質N=1と同じ結果に。 温度が高すぎると構造化出力が壊れ始めます 💥 JSONのフィールド名が揺れたり、型が合わなくなったり。ハルシネーションも増加し、固有名詞・数値・日付の正確性が崩壊します。ツール呼び出しの不安定化、再現性の喪失も深刻な問題です。 温度によるリトライコストの増加も計測してください。スキーマ違反率が概ね5%を超えたら温度を下げることを検討しましょう。 🛠️ ユースケース エージェント内の経路ごとに温度を変えるのが基本 🔀 計画ステップは0.3〜0.5、ツール呼び出しの引数生成は0.0〜0.2、ユーザー向け応答は0.5〜0.7。モデルを切り替える際に温度も同時に切り替えると自然です。 Best-of-Nを使うなら温度を上げる必要があります。温度0でN=5を生成しても、ほぼ同一の候補が5つ返るだけです。N>1のときは0.5〜0.8に設定し、多様な候補の中からJudgeが最良を選ぶ構成にします。 top_pとの併用には注意 ⚠️ 温度とtop_pを両方変更すると効果が掛け算になり、予測困難な挙動を示します。原則としてどちらか一方だけを調整してください。 #AIエージェント# #ソフトウェアアーキテクチャ#