0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

連載:AIに仕事を奪われる不安から始めるハーネス作成入門 第4回 task_request / task_resultでAIエージェントの仕事を契約化する

0
Last updated at Posted at 2026-06-11

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で構造化し、「契約」として扱うことで、再現性・検証性・ログ可能性が向上する です。

要点は以下です。

  1. task_requestで「何をしてほしいか」を構造化し、指示の曖昧さを減らす
  2. task_resultで「何が返ってきたか」を構造化し、検証とログを可能にする
  3. 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回の連載を予定しています ─

連載情報

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?