task_request / task_resultでAIエージェントの仕事を契約化する
連載:AIに仕事を奪われる不安から始めるハーネス作成入門
全24回(週2回・12週間)|第4回 / 24この連載は、AIによるキャリア不安を持つプログラマ・SEに向けて、AIエージェントを安全に制御・検証・運用するための「ハーネス」を作る技術を、段階的に学ぶシリーズです。
はじめに:この記事で扱う不安
この記事は連載「連載:AIに仕事を奪われる不安から始めるハーネス作成入門」の 第4回 です。
第2回では最小構成(AIエージェント + MCPサーバー + task_request / task_result)をMermaid図で設計し、第3回では「使う」と「運用する」の違いを整理しました。今回は、その最小構成の中核であるtask_request / task_resultの設計について整理します。
この記事で扱う不安は、次のようなものです。
AIエージェントに自然言語で指示を出しているが、指示の再現性が低く、結果の品質が安定しない。構造化の方法がわからない。
この不安は自然です。自然言語のプロンプトは柔軟ですが、同じ指示でも結果が変わります。業務では「昨日と今日で違う結果が返ってくる」のは困ります。
この記事では、AIへの指示と結果をJSONで構造化する「契約」の設計方法を示します。
対象読者
- AIエージェントへの指示の再現性に困っているプログラマ
- API設計やインターフェース定義の経験があるSE
- AIの入出力を構造化したいが、どんなJSONスキーマにすればよいか迷っているエンジニア
結論
先に結論を書くと、AIエージェントへの指示と結果をJSONで構造化し、「契約」として扱うことで、再現性・検証性・ログ可能性が向上する です。
要点は以下です。
- task_requestで「何をしてほしいか」を構造化し、指示の曖昧さを減らす
- task_resultで「何が返ってきたか」を構造化し、検証とログを可能にする
- API設計の経験がある人にとって、この「入出力の契約化」は馴染みのある作業
なぜ「契約」が必要なのか
自然言語プロンプトの限界
自然言語のプロンプトは柔軟ですが、以下の問題があります。
| 問題 | 具体例 |
|---|---|
| 曖昧性 | 「いい感じに作って」の「いい感じ」が定義されていない |
| 再現性の低さ | 同じ文章でも実行ごとに結果が変わる |
| 検証の困難 | 「期待する出力」が明確でないため、合否判定ができない |
| ログの不十分 | 「何を指示したか」の記録が曖昧になる |
「契約」という考え方
API設計では、リクエストとレスポンスの形式を明確に定義します。REST APIならリクエストボディとレスポンススキーマ、gRPCならProtocol Buffersで定義します。
AIエージェントでも同じです。「何を渡し、何が返ってくるか」をJSONで定義することで、「契約」ができます。これが task_request / task_result です。
既存のSE / プログラマ経験をどう活かせるか
task_request / task_resultの設計は、API設計の経験がそのまま活きる領域です。
| 既存経験 | task_request / task_result設計での活かし方 |
|---|---|
| REST APIのリクエスト/レスポンス設計 | task_requestの入力フィールドとtask_resultの出力スキーマ定義 |
| JSON Schema / OpenAPI定義 | task_requestのバリデーションルール設計 |
| エラーハンドリング設計 | task_resultのステータスコードとエラーメッセージ設計 |
| バージョニング・後方互換性 | task_requestのスキーマバージョン管理 |
「入力と出力を明確に定義し、異常系も含めて設計する」という経験は、AIハーネス設計でそのまま使えます。
task_requestの設計
必須フィールド
以下が、task_requestの必須フィールドです。
| フィールド | 型 | 説明 |
|---|---|---|
task_id |
string | タスクの一意識別子。ログや再実行の追跡に使う |
task_type |
string | タスクの種類。エージェントが処理を切り替える基準 |
input |
object | タスクに必要な入力データ |
オプションフィールド
以下は、運用が進むにつれて追加するフィールドです。最初から全部入れる必要はありません。
| フィールド | 型 | 説明 | 追加時期の目安 |
|---|---|---|---|
constraints |
array | 出力の制約条件 | 最初から |
quality_gate |
object | 品質ゲートの基準 | 第17〜18回 |
model_preference |
string | 使用LLMの指定 | 第11〜12回 |
log_level |
string | ログ出力の詳細度 | 第13〜14回 |
approval_required |
boolean | 人間承認が必要か | 第15〜16回 |
timeout_seconds |
integer | タイムアウト設定 | 必要に応じて |
task_requestのJSONテンプレート
以下が、実用的なtask_requestのJSONテンプレートです。これが今回の最も重要な成果物です。
{
"task_request": {
"task_id": "review_api_design_001",
"task_type": "code_review",
"input": {
"target_file": "src/api/users.py",
"review_focus": ["security", "error_handling", "naming"],
"context": "REST APIのユーザー管理エンドポイント"
},
"constraints": [
"指摘は重要度順に並べる",
"各指摘に修正案を含める",
"セキュリティ問題は別セクションでまとめる"
]
}
}
このJSONを見て、「これはAPIのリクエストボディと似ている」と感じた方もいると思います。その通りで、API設計の経験がそのまま活きます。
task_resultの設計
必須フィールド
| フィールド | 型 | 説明 |
|---|---|---|
task_id |
string | 対応するtask_requestのtask_id |
status |
string |
completed / failed / partial
|
output |
object | タスクの実行結果 |
オプションフィールド
| フィールド | 型 | 説明 |
|---|---|---|
error |
object | エラー情報(statusがfailedのとき) |
metadata |
object | 実行時間・使用モデル・トークン数など |
warnings |
array | 完了したが注意が必要な点 |
task_resultのJSONテンプレート
先ほどのtask_requestに対応するtask_resultの例です。
{
"task_result": {
"task_id": "review_api_design_001",
"status": "completed",
"output": {
"findings": [
{
"severity": "high",
"category": "security",
"description": "ユーザーIDの入力検証が不足している",
"suggestion": "UUID形式のバリデーションを追加する",
"line_range": "L42-L48"
}
],
"summary": "セキュリティ上の指摘が1件あります"
},
"metadata": {
"model": "gemini-2.5-pro",
"execution_time_ms": 3200,
"token_count": {"input": 1500, "output": 800}
}
}
}
エラー時のtask_result
AIエージェントが失敗した場合も、構造化された結果が返るように設計します。これは、APIのエラーレスポンス設計と同じ考え方です。
{
"task_result": {
"task_id": "review_api_design_001",
"status": "failed",
"output": null,
"error": {
"code": "TOOL_UNAVAILABLE",
"message": "MCPサーバーへの接続がタイムアウトしました",
"retryable": true
}
}
}
正常系だけでなく異常系も設計することで、障害時の調査や自動リトライが可能になります。
プロンプトと契約の併用
task_requestは自然言語プロンプトを置き換えるものではありません。両者を併用します。
| 役割 | 担当 |
|---|---|
| 「何をしてほしいか」の構造化 | task_request(JSON) |
| 「どうやってほしいか」の補足 | 自然言語プロンプト |
| 「何が返ってきたか」の構造化 | task_result(JSON) |
task_requestが「契約書」、プロンプトが「口頭での補足説明」と考えるとわかりやすいです。契約書があるからこそ、「何を約束したか」が明確になり、検証やログが可能になります。
実装・設計時の注意点
| 注意点 | 理由 | 対策 |
|---|---|---|
| 最初からフィールドを詰め込みすぎない | 複雑なスキーマは運用負荷が高い | 必須フィールドから始め、必要に応じて追加 |
| task_idの命名規則を決める | ログ検索時に規則がないと見つけられない |
{task_type}_{target}_{連番} のような規則を決める |
| エラー時のtask_resultも必ず設計する | 異常系が未設計だと障害調査ができない | status + errorフィールドを必ず含める |
今回の小さな成果物
- 上のtask_request JSONテンプレートを自分の業務に合わせて書き換える
- 対応するtask_result(正常系 + エラー系)も作成する
-
作成したJSONをGitHubリポジトリの
templates/ディレクトリに保存する
まとめ
この記事では、AIエージェントへの指示と結果をJSONで構造化する task_request / task_result の設計について整理しました。
重要なのは、自然言語プロンプトだけでは確保できない「再現性」「検証性」「ログ可能性」を、JSONによる構造化で実現する ことです。
API設計やインターフェース定義の経験がある人にとって、この「入出力の契約化」は馴染みのある作業です。その経験をAIハーネス設計に活かしてください。
次回予告
第5回:SEの設計経験をAIエージェント制御に転用する(火曜日公開予定)
次回は、SEの設計経験をAIハーネス設計にどう転用するかを、より具体的に整理します。
次回扱う内容:
- 要件整理・責務分離・インターフェース設計の経験をAIハーネスに転用する対応表
- 「人間が設計し、AIが実行する」という役割分担の考え方
- 設計経験を活かせる具体的なシナリオ
次回の成果物:
- 対応表(SE経験 → AIハーネス設計への転用マップ)
次回までに試しておくと良いこと:
- 今回作成したtask_request JSONをGitHubに保存する
- 自分の設計経験の中で、「AIハーネスに活かせそう」と感じるものを1つ挙げておく
連載目次
| 回 | タイトル | 状態 |
|---|---|---|
| 1 | AIに仕事を奪われる不安から「ハーネス作成」を学ぶ理由 | ✅ |
| 2 | 最小構成のAIハーネスをMermaidで設計してみる | ✅ |
| 3 | AIにコードを書かせるだけでは足りない理由 | ✅ |
| 4 | task_request / task_resultでAIエージェントの仕事を契約化する(この記事) | 📖 |
| 5 | SEの設計経験をAIエージェント制御に転用する | 次回 |
| 6 | ハーネス用のディレクトリ構成とREADMEを作る | ─ |
| ... | 全24回の連載を予定しています | ─ |
連載情報
- 連載名:連載:AIに仕事を奪われる不安から始めるハーネス作成入門
- 全24回(12週間・週2回)
- 著者: @singula00991
- 投稿曜日:火曜日(キャリア・設計・概念)/ 金曜日(実装・検証・テンプレート)