AIエージェントの性能は、なぜモデルだけで決まらないのか？安全に動かすハーネス設計の10要素

南翔伍 / AIコンパニオンとSNSの間くらいの「Jams」開発中

2026年7月19日 06:02

高性能なモデルを選び、丁寧な指示を書き、必要なツールも接続した。

最初の数回はうまく動く。ところが、仕事が長くなると、少しずつ崩れ始めます。

途中で目的を見失う。関係のないファイルを変更する。同じ処理を繰り返す。前の判断を忘れる。外部サービスへ誤った内容を登録する。中断すると、どこから再開すればよいか分からない。

そこで、さらに強いモデルへ替えたり、プロンプトを長くしたり、エージェントを追加したりします。

もちろん、モデル性能や指示は重要です。ただ、それだけでは解決しない問題があります。

AIエージェントの実務性能は、モデル単体ではなく、必要な情報、ツール、状態、権限、検証、観測、回復手段をどう結びつけたかで決まるからです。

この周囲の実行設計を、この記事では「AIハーネス」と呼びます。

フェーズ9では、人間・AI・既存システムの役割、承認、例外、状態を含む業務フローを設計しました。

フェーズ10では、その設計を実際に動かせる基盤へ落とします。

今回は、AI活用成熟度12フェーズのフェーズ10「AI実行基盤・ハーネス設計」として、AIエージェントを安全かつ再現可能に働かせる10の設計要素を整理します。

AI活用成熟度12フェーズの記事一覧

フェーズ9で業務フローを設計した次は、実行基盤へ落とす

フェーズ9では、AIを既存工程へ追加するだけではなく、価値が届くまでの流れ全体を再設計しました。

扱ったのは、例えば次の要素です。

誰へ何の価値を届けるか
業務の開始点と終了点
不要な工程や重複
AI・人間・既存システムの役割
中間成果物
処理状態
承認
例外
復旧
KPIとガードレール

ここまで設計すると、To-Beの業務フローは見えるようになります。

ただし、業務フロー図だけでは実際に動きません。

例えば「AIが問い合わせを分類する」という一工程でも、実装時には次を決める必要があります。

どのモデルを使うか
どの顧客情報を渡すか
どの分類基準を参照するか
どのToolを呼べるか
どの情報を正式な状態として保持するか
どの分類なら人間承認が必要か
誤分類をどう検知するか
外部システムへの登録にどの権限を使うか
途中で失敗した場合にどこから再開するか
同じ案件を二重登録しないために何を確認するか

フェーズ9が「どう働くかを設計する段階」なら、フェーズ10は「その働き方を、安全かつ再現可能に実行する仕組みを作る段階」です。

一方、作った仕組みを本番データで継続評価し、モデルやToolの変更、費用、インシデント、利用規程まで管理するのは、次のフェーズ11です。

フェーズ10では、評価・監視・復旧が可能な基盤を作るところまで扱います。

AIエージェントとハーネスは同じものではない

最初に、二つの言葉を分けておきます。

現在の代表的なAgent SDKには、モデル、指示、Tool、状態管理、人間介入、Tracingなどを組み合わせるための機能があります。

ただし、「ハーネス」は各社製品で完全に統一された仕様名ではありません。

この記事では、モデルの周囲にある実行制御全体を説明するための整理概念として使います。

エージェントは、目標に沿って次の行動を選ぶ実行主体

一回限りの生成では、入力に対して出力を返せば処理は終わります。

エージェント型の実行では、モデルが状況に応じて次の行動を選びます。

情報を調べる
Toolを呼ぶ
ファイルを読む
コードを変更する
不足情報を質問する
別のAgentへ処理を渡す
結果を評価する
修正する
完了条件を確認する

このように、目標へ向かって複数回の判断と実行を行う主体を、ここではエージェントと呼びます。

OpenAI Agents SDKでは、AgentにInstructions、Tools、Handoffs、Guardrails、出力型などを設定し、RunnerがTool利用や複数ターンの実行を管理します。

AnthropicのAgent SDKも、Claude Codeで使われるAgent loop、Tool、Context管理をPython・TypeScriptから利用できる基盤として提供されています。

ハーネスは、何を参照し、何を実行し、どう検証・回復するかを規定する

エージェントが強くても、自由に動かせばよいわけではありません。

ハーネスは、エージェントの周囲に次を用意します。

目的と仕様
参照情報
作業手順
Tool
状態
メモリ
権限
秘密情報
隔離環境
人間承認
Guardrail
Test
Trace
失敗後の再開
フォールバック
ロールバック

この記事では、ハーネスを次のように定義します。

AIモデルが、必要な情報とToolを使い、許可された範囲で、観測・検証・停止・再開可能な形で業務を実行するための制御層。

これは本記事上の整理です。特定SDKの正式な製品定義を指すものではありません。

プロンプトは、ハーネスの一要素にすぎない

プロンプトには、目標、背景、制約、出力形式などを書けます。

しかし、プロンプトだけでは次を確実に強制できない場合があります。

特定ファイル以外を変更しない
本番データを削除しない
必ずTestを通す
二重送信を防ぐ
秘密情報へアクセスしない
承認前に公開しない
失敗時に前の状態へ戻す

説明だけで守らせるのではなく、Toolの権限、Sandbox、承認、Test、実行環境へ制約を移す必要があります。

自律性が高いほど成熟しているわけではない

人間へ質問せず、最後まで自動で進めるAgentは高度に見えます。

しかし、質問すべき場面で勝手に仮定し、承認すべき操作を自動実行するなら、実務では危険です。

成熟度を測るのは、エージェントが一人で何工程できるかではありません。

必要なときに止まれるか
不確実性を検知できるか
人間へ適切に渡せるか
失敗を限定できるか
同じ条件で再現できるか
誰が責任を持つか

このような制御可能性の方が重要です。

AIハーネスを構成する10の設計要素

AIハーネスは、特定製品の設定画面を埋めることではありません。

どのSDKやクラウドを使う場合でも、少なくとも次の10領域を確認します。

Goal・Specification
Model・Routing
Context・Knowledge
Instructions・Skills・Rules
Tools・API・MCP
Session・State・Memory・Artifacts
Permissions・Secrets・Sandbox
Human-in-the-loop・Guardrails
Trace・Logs・Tests
Recovery・Fallback・Change Management

これらは、1から10へ順番に成熟する段階ではありません。

相互に依存する設計領域です。

例えばToolを追加すれば、権限、承認、Trace、Recoveryの設計も変わります。モデルを変更すれば、出力品質だけでなく、Tool選択、Context量、費用、Test結果も変わる可能性があります。

Goalが曖昧なら、エージェントは正しく迷う

最初に固定するのはモデルではなく、目的と完了条件です。

例えば「Webサイトを改善する」というGoalだけでは、判断できません。

少なくとも次を定義します。

対象ページ
改善目的
参照するDesign
変更してよい範囲
変更してはいけない範囲
必須機能
対応画面幅
Test条件
完了成果物
本番反映の可否
停止条件

完了条件が曖昧だと、Agentは修正を続けるか、見た目だけで完了と判断する可能性があります。

Goalは「何を作るか」だけでなく、「何をもって完了と判定するか」まで含めます。

モデル選択は、賢さだけでなく速度・費用・安定性で決める

最上位モデルをすべての工程へ使えば、設計が簡単に見えます。

しかし、業務には性質の異なる工程があります。

曖昧な要件を整理する
計画を作る
大量ファイルから対象を探す
定型変換を行う
コードを実装する
Test失敗を分析する
最終結果をレビューする

各工程で必要な能力は同じではありません。

モデル選択では次を確認します。

推論の難しさ
Context量
Tool利用能力
構造化出力の安定性
応答速度
費用
利用制限
データ要件
再現性
フォールバック可能性

モデル名をハーネス全体へ直接埋め込むと、変更時の影響が広がります。

工程ごとの役割と入出力を固定し、その役割を満たすモデルを差し替えられる構造にします。

Contextと業務状態を混ぜると、長時間作業が崩れる

長い仕事では、多くの情報を扱います。

しかし、すべてを会話履歴へ入れ続ければよいわけではありません。

製品によって用語と実装は異なりますが、少なくとも次を区別します。

Context：現在の判断に必要な材料
Session：一つの対話・実行スレッド
State：その実行が現在どこまで進んでいるか
Memory：複数回の実行をまたいで再利用する情報
Artifact：作成・保存・版管理する成果物

Google ADKでは、Sessionを一つの会話スレッド、StateをSession内の一時データ、Memoryをセッション横断の検索可能な情報として整理しています。またArtifactは、名前と版を持つファイル等のデータとして扱われます。

会話履歴の圧縮や要約によって失ってはいけない情報は、正式なStateやArtifactへ外出しします。

Instructions・Skills・Rulesは、失敗を仕組みへ戻す単位になる

AIが失敗するたびに、次回のプロンプトへ注意事項を追加すると、指示は長くなります。

そこで役割を分けます。

Prompt：今回の依頼
Rule：継続して守る制約
Skill：再利用する専門手順
Command：決まった作業を開始する入口
Hook・Callback：特定イベントで実行する処理
Test：結果が条件を満たすか確認する仕組み

文章で書いたRuleが必ず守られるとは限りません。

重大な制約は、Tool権限、Guardrail、Test、Sandboxへ移します。

Tool契約が曖昧だと、誤った操作を選ぶ

Agentは、Toolの名前、説明、入力Schema等を見て、どれを使うか判断します。

Tool設計では次を明確にします。

Tool名
何をするToolか
何をしないToolか
入力
出力
Error
副作用
必要権限
承認条件
Timeout
再実行可能性

「顧客を更新する」のような広いToolより、「顧客メモのDraftを作成する」「承認済みメモを保存する」のように分けた方が制御しやすくなります。

MCPではServerがToolを名前とSchema等のMetadata付きで公開できますが、プロトコル自体は特定の承認UIや業務権限モデルを強制しません。

権限を広くすると、失敗範囲も広がる

Agentが多くのToolへアクセスできれば便利になります。

同時に、誤操作できる範囲も広がります。

本記事では、導入時の推奨順序を次の5段階で整理します。

1. Read-only
2. Draft
3. Dry-run
4. Limited write
5. Approved production

これは公的な成熟度標準ではなく、可逆性を保ちながら権限を広げるための実務フレームです。

最初から削除、公開、送信、課金、権限変更を許可しません。

OpenAI Agents SDKのSandbox Agentsは、ファイル検索、編集、コマンド実行、Artifact生成等を隔離されたWorkspaceで行い、保存済みのSandbox状態から再開できるベータ機能として案内されています。

一般にサンドボックスを採用する場合も、ネットワーク、ファイル、Secret、本番サービスへの境界を別途設計する必要があります。

人間承認は、操作前の正式な状態として実装する

「公開前に人が確認する」と手順書に書くだけでは不十分です。

承認が必要なTool callでは、実行を中断し、承認対象を人間へ提示し、承認または拒否の後に処理を再開する構造が必要です。

OpenAI Agents SDKのHuman-in-the-loopでは、承認対象のTool callをInterruptionとして表面化し、RunStateを保存して、判断後に再開できます。

業務上は次を定義します。

承認対象
承認者
提示する情報
判断基準
回答期限
代理承認者
承認
拒否
修正要求
中止
再開地点

人間介入は承認だけではありません。

不足情報の提供、例外判断、差し戻し、処理中止も含みます。

Traceがなければ、成功も失敗も再現できない

Agentの実行では、最終出力だけを見ても原因が分からないことがあります。

途中で、どのモデルが何を判断し、どのToolをどの引数で呼び、どこでHandoffし、どのGuardrailが作動したかを追える必要があります。

OpenAI Agents SDKのTracingは、LLM生成、Tool call、Handoff、Guardrail、独自イベントをTraceとSpanとして記録し、開発・本番のデバッグ、可視化、監視に利用できます。

ただし、入力・出力やTool引数を保存すると、機密情報や個人情報が含まれる可能性があります。

設計時に次を決めます。

記録するイベント
記録しないデータ
Masking
閲覧者
保存期間
業務IDとの対応
障害調査に必要な粒度
評価利用の可否

ログ量が多いことと、観測可能であることは同じではありません。

回復手段がなければ、本番運用できない

Agentは失敗します。

重要なのは、失敗しないと仮定することではなく、失敗を分類し、影響を限定し、再開できるようにすることです。

最低限、次を設計します。

Timeout
Retry
Retry上限
一時的失敗
恒久的失敗
Checkpoint
冪等性
Fallback
Rollback
手動復帰
中止条件
変更履歴

この設計がない状態で、外部システムへWrite権限を与えるべきではありません。

モデルは、タスクと工程ごとに選ぶ

モデル選択は、ハーネス全体の一部です。

「最も賢いモデルを一つ選ぶ」という判断だけでは、速度、費用、利用制限、安定性を最適化できません。

すべてを最上位モデルへ任せる必要はない

例えば、次の作業は比較的定型的です。

ファイル名を分類する
既定形式へ変換する
必須項目の有無を確認する
JSONを生成する
Test結果を短く要約する

一方、次はより高い推論力が必要かもしれません。

曖昧な要件を整理する
複数の制約を満たす実装計画
重大な不具合の原因分析
相反する設計案の比較
例外の扱いを決める

工程を分ければ、必要な能力に応じたモデルを割り当てられます。

計画、実行、検証を同じ視点だけで行わない

一つのAgentが計画し、実装し、自分の実装を採点すると、同じ思い込みを引き継ぐ可能性があります。

状況に応じて次を分けます。

計画
実行
Test
独立レビュー
人間承認

必ず複数Agentへ分ける必要はありません。

別のPrompt、Test、静的解析、スクリーンショット比較でも独立性を作れます。

Fallbackは、単に安いモデルへ落とすことではない

Fallbackとは、第一選択が使えないときの代替経路です。

例えば次があります。

別モデルへ切り替える
定型ルールへ戻る
Toolを使わず、人間へ渡す
Read-onlyの結果だけ返す
前回の承認済み版を使う
処理を停止する

モデルの障害時に自動で別モデルへ切り替えても、そのモデルが同じ品質、Tool能力、Context量を持つとは限りません。

Fallback先でも完了条件を満たせるかを確認します。

モデル変更時の影響範囲を限定する

モデルを更新したとき、業務全体の挙動が変わる可能性があります。

特に影響を受けるのは次です。

Tool選択
出力形式
長文Contextの扱い
例外判断
自己停止
費用
速度

工程の入出力契約を明確にし、モデル変更の影響を一つの工程へ限定します。

継続的な回帰評価はフェーズ11で扱いますが、フェーズ10の時点で差し替え可能な構造を作ります。

Context・Session・State・Memory・Artifactを分ける

長時間稼働するAgentでは、情報管理が品質を左右します。

すべてを同じ会話へ詰め込むのではなく、役割別に分けます。

Contextは、現在の判断に必要な材料

Contextには、今回の行動を決めるために必要な情報を入れます。

例えばWebサイト修正なら次です。

対象ページ
要件
Design
現在のコード
関連コンポーネント
Coding rules
Test条件
既知の不具合

関係のない過去案件や旧版資料を大量に渡すと、誤参照の原因になります。

Sessionは、一つの実行や対話のまとまり

Sessionは、一連の会話や実行イベントを関連付ける単位です。

同じユーザーでも、別案件や別目的の作業を一つのSessionへ混ぜない方がよい場合があります。

Stateは、業務が今どこまで進んでいるか

Stateには、現在の実行位置を保持します。

計画作成済み
人間承認待ち
実装中
Test失敗
修正中
Review待ち
Deploy承認待ち
完了
中止

Stateを持てば、中断後にどこから再開するか判断できます。

Memoryは、次回以降に再利用する情報

Memoryには、別の実行でも役立つ情報を置きます。

ユーザーの長期的な好み
プロジェクトの恒常ルール
過去の失敗パターン
よく使う用語
継続案件の判断履歴

短期的な作業途中の状態をMemoryへ混ぜると、次回の処理を誤らせる可能性があります。

Artifactは、作成・保存・版管理する成果物

Artifactは、Agentが作った成果物です。

計画書
変更ファイル
レポート
スクリーンショット
Test結果
Diff
承認済み出力

正式なArtifactには、名前、版、作成日時、関連する業務IDを持たせます。

会話履歴を正式状態として使わない

会話履歴には、仮説、撤回、誤り、途中案が混ざります。

正式な状態や確定成果物は、別に保存します。

Contextが圧縮・要約された場合にも、次を失わないようにします。

Goal
完了条件
現在State
承認済み判断
変更対象
Test結果
次の行動
Rollback先

Instructions・Skills・Rulesをどう分けるか

指示が増えると、すべてを一つのSystem promptへ入れたくなります。

しかし、変更頻度と役割が違うものを分けた方が管理しやすくなります。

Promptは、今回の依頼

Promptには、その実行固有の目的や入力を書きます。

今回修正するページ
今回の不具合
今回の期限
今回の出力形式

毎回変わる情報です。

Ruleは、継続して守る制約

Ruleには、案件や組織で継続して守る条件を書きます。

本番へ直接Commitしない
顧客名を公開しない
指定ディレクトリ以外を変更しない
Test失敗時は完了としない
秘密情報を出力しない

ただし、重大なRuleを文章だけに依存させません。

Skillは、再利用する専門手順

Skillには、特定種類の仕事を行うための方法をまとめます。

デザイン再現
PDF生成
セキュリティレビュー
記事ファクトチェック
データ移行
Pull Requestレビュー

Skillには、適用条件、手順、入力、出力、失敗例、確認方法を含めます。

Commandは、作業を始める入口

Commandは、決まった仕事を一定形式で開始する入口です。

例えば次です。

`/review-pr`
`/generate-report`
`/check-design`
`/deploy-preview`

利用者が毎回長い依頼を書かなくても、必要な入力をそろえて開始できます。

Hook・Callbackは、特定イベントで必ず行う処理

HookやCallbackは、特定のタイミングで処理を差し込む仕組みです。

Tool実行前に入力を検証する
ファイル変更後にLintを走らせる
Session終了時にStateを保存する
承認前にDiffを作る
失敗時に通知する

AnthropicのAgent SDKはPermissions、Hooks、Checkpointing、Observability等の制御機能を持ち、Claude CodeのSubagentには個別のTool accessやPermissionsを設定できます。

説明だけで守れないRuleは、Test・権限へ移す

「本番へ直接Deployしない」とPromptへ書くだけでは弱いものです。

より確実にするには次を行います。

本番Credentialを渡さない
Deploy Toolに承認を必須化する
Protected branchを使う
CIが成功しなければMergeできない
Sandbox外へ書き込めないようにする

Ruleを、実行環境の制約へ変換します。

Tools・API・MCPは、接続ではなく契約として設計する

Toolをつなげると、Agentは外部へ働きかけられるようになります。

同時に、副作用と権限が生まれます。

Tool名と説明が曖昧だと誤選択が起きる

例えば次のToolがあったとします。

`save`
`update`
`send`

何を保存・更新・送信するのか分かりません。

より明確にします。

`create_customer_note_draft`
`save_approved_customer_note`
`send_reviewed_email`
`archive_processed_message`

Tool説明には、使用条件と使用禁止条件も含めます。

入力Schemaと出力Schemaを固定する

自然文だけでTool引数を渡すと、欠落や誤解が起きます。

入力を構造化します。

customer_id:
note_body:
source_message_id:
approval_id:
idempotency_key:

出力も分けます。

status:
created_record_id:
already_existed:
warnings:
error_code:

Agentが結果を解釈しやすくなり、Testもしやすくなります。

ReadとWriteを分ける

顧客情報を読むToolと、顧客情報を更新するToolは分けます。

Read-onlyの検証段階では、Write ToolをAgentへ見せない選択もできます。

Toolが存在するだけで、誤選択の可能性が生まれます。

不要なToolは公開しません。

DraftとPublishを分ける

メールやSNS投稿では、内容作成と送信を分けます。

下書き作成
→ 人間確認
→ 承認済みDraft
→ 送信

「作って送る」を一つのToolにすると、内容確認前に外部影響が発生します。

MCPは接続を標準化するが、権限までは決めない

MCPは、LLMアプリケーションと外部データ・Toolを接続するためのオープンプロトコルです。

2026年7月17日時点で公開されている仕様は2025-11-25版です。MCPはHost、Client、Server間の通信、Capability negotiation、ToolやResource等の提供方法を定義します。

しかし、MCPを使うだけで次が決まるわけではありません。

誰が利用できるか
どのデータを読めるか
どの操作を書き込めるか
承認が必要か
監査ログをどう残すか
結果が正しいか

MCPは接続契約です。

業務権限と統制は、ハーネス側で設計します。

不要なToolをエージェントへ見せない

Toolが多いほど高機能に見えます。

しかし、選択肢が増えれば、誤ったToolを選ぶ可能性やContext負荷も増えます。

Agentの役割ごとに必要なToolだけを渡します。

権限・秘密情報・Sandboxで失敗範囲を限定する

安全設計では、Agentを信頼するかどうかより、誤った場合に何が起きるかを考えます。

最小権限から始める

本記事では、次の順序を推奨します。

Read-only：読む・検索する
Draft：成果候補を作るが外部反映しない
Dry-run：実行予定内容と影響を表示する
Limited write：限定範囲へ書き込む
Approved production：人間承認後だけ本番操作する

権限を広げる条件は次です。

正常ケースが通る
代表的な例外で止まれる
Testで検証できる
Traceから原因を追える
二重処理を防げる
手動復帰できる

本番認証情報をPromptやファイルへ置かない

API key、Access token、Passwordを、Prompt、共有ファイル、Repositoryへ直接書きません。

Secret managerや実行環境のCredential機能を利用し、Agentには必要な操作だけをTool経由で与えます。

秘密情報を直接読ませる必要がない構成を優先します。

ファイル・Shell・Network・外部サービスを分けて許可する

一つの「フルアクセス」権限にまとめません。

ファイルRead
ファイルWrite
Shell command
Network access
Package install
Browser操作
外部API
本番サービス

それぞれを必要性に応じて許可します。

開発・検証・本番を分ける

開発環境でAgentが自由に試せても、本番では同じ権限を与えないことがあります。

開発：実験と失敗を許容
検証：本番相当条件でTest
本番：権限・操作・変更を限定

Test用データと本番データも分けます。

AI生成物と本番反映を分ける

Agentがコード、設定、文書を生成した時点では、本番反映しません。

次を挟みます。

Diff
Lint
Test
Build
Preview
Screenshot
Review
人間承認

生成と公開を別工程にすることで、可逆性を高めます。

Human-in-the-loopとGuardrailは、異なる役割を持つ

Human-in-the-loopとGuardrailは、どちらも安全に関係しますが、役割が違います。

Guardrailは、機械的に判定できる条件を扱う

例えば次です。

必須入力があるか
JSON Schemaに合うか
個人情報らしき文字列が含まれるか
許可されていないToolか
金額が上限を超えていないか
対象ディレクトリ外を変更していないか
Testが成功したか

明確な条件を自動確認します。

OpenAI Agents SDKのGuardrailは入力・出力の検証に利用でき、Tool Guardrailは個別Tool callへ適用できます。

ただし、一つのGuardrailが複数AgentやすべてのToolへ自動的に同じ範囲で適用されるとは限りません。設計対象ごとに適用位置を確認する必要があります。

Human-in-the-loopは、価値判断や例外判断を扱う

例えば次です。

この文章を顧客へ送ってよいか
例外を受け入れるか
Design差分が許容範囲か
重大な変更を本番へ入れるか
複数案のどれを採用するか
リスクと便益のどちらを優先するか

定型条件だけでは決められない判断です。

すべてを人間確認にすると二重作業になる

人間へ全出力を最初から読み直させれば、安全になるとは限りません。

確認量が多すぎると、形式的に承認される可能性があります。

人間には次を提示します。

変更概要
重要Diff
Test結果
未確認事項
例外
リスク
推奨判断
Rollback方法

判断に必要な情報を圧縮します。

承認者、期限、差し戻し、再開地点を決める

承認を待つ間、AgentのStateを保存します。

承認後に最初から再実行すると、重複や別結果が起きる可能性があります。

承認フローには次を含めます。

Pending approval
Approved
Rejected
Changes requested
Expired
Cancelled
Resume point

承認できない操作は、最初から権限を与えない

人間承認を入れても、Agentが承認前にToolを呼べるなら意味がありません。

承認が完了するまでWrite Toolを実行できない構造にします。

Trace・Logs・Testsで、実行を説明可能にする

「結果が正しそう」だけでは、本番運用できません。

何が起きたかを追跡し、同じ条件で検証できる必要があります。

Traceは、一連の実行をつなぐ

Traceは、一つの依頼から完了までの流れをまとめます。

その中にSpanとして次を記録できます。

Model call
Tool call
Handoff
Guardrail
Human approval
Test
Error
Custom event

Logは、個別の事象を記録する

Logには次を残します。

時刻
Agent
Tool
Status
Error code
Duration
Retry count
Record ID

TraceとLogを同じ意味で使わず、全体の流れと個別イベントを分けます。

Diffは、何が変わったかを示す

コード、文書、設定では、変更前後を比較します。

Diffにより次を確認できます。

対象外ファイルを変えていないか
不要な削除がないか
秘密情報を追加していないか
要件に対応しているか

Previewは、利用者が結果を確認する

WebサイトならPreview URL、文書ならPDF、メールならDraftとして確認します。

完成物を実際の利用形態に近い状態で確認します。

Testは、完了条件を機械的に確認する

Testには次があります。

Unit test
Integration test
Schema validation
Lint
Build
Link check
Screenshot comparison
Required-field check

すべてを人間の目視へ依存させません。

機微情報をLogへ残しすぎない

観測のために、入力全文やTool引数を保存したくなります。

しかし、個人情報、秘密情報、顧客データが含まれる可能性があります。

次を設計します。

保存しない項目
Masking
Hash化
参照IDだけ記録
保存期間
閲覧権限
削除手順

失敗しても戻れるようにする

実行基盤では、成功ルートだけでなく失敗後の動きを設計します。

一時的失敗と恒久的失敗を分ける

一時的失敗の例です。

Network timeout
一時的なRate limit
外部APIの短時間障害
一時的なServer error

恒久的失敗の例です。

入力不足
権限不足
Schema不一致
対象外データ
削除済みRecord
禁止操作

恒久的失敗を何度Retryしても解決しません。

Retryには回数・間隔・上限を置く

Retryでは次を決めます。

最大回数
待機間隔
Backoff
Jitter
総時間上限
RetryしないError
失敗後の通知先

無限Retryを防ぎます。

冪等性で二重送信・二重登録を防ぐ

外部操作では、処理が成功した後にResponseだけ受け取れなかった可能性があります。

その状態でRetryすると、同じ操作が二度実行されます。

そこで、一意な処理Keyや既存状態を使い、同じ要求を複数回実行しても結果が重複しないようにします。

Idempotency key
Source message ID
Job ID
Existing record check
Completion marker

Checkpointから再開する

長い処理では、工程ごとに確定状態を保存します。

計画承認済み
→ 実装完了
→ Test成功
→ Review承認済み
→ Deploy待ち

途中で止まっても、承認済み工程を繰り返さずに再開できます。

Fallback経路を用意する

第一経路が使えない場合の代替を決めます。

別モデル
別Tool
手動処理
Read-only出力
前回の承認済み版
処理中止

Fallbackによって品質や機能が下がる場合は、利用者へ明示します。

Rollback可能な操作と不可能な操作を分ける

コードDeployや設定変更は、前の版へ戻せる場合があります。

一方、送信済みメール、外部公開、支払い、削除は、完全には取り消せない場合があります。

取り消しにくい操作ほど、事前承認を強くします。

単一エージェントか、複数エージェントか

複数Agentを使えば、役割を分けられます。

ただし、構成は複雑になります。

一つで扱えるなら分けない

同じContext、同じTool、同じ権限、同じ完了条件で処理できるなら、一つのAgentで十分な場合があります。

分割にはコストがあります。

Context引き継ぎ
State共有
重複作業
Handoff失敗
Trace複雑化
Test増加
費用増加

Context・権限・責任が違う場合に分ける

分ける理由が明確な例です。

調査AgentはWeb Read-only
実装AgentはRepository Write
Review AgentはWrite不可
Deploy Agentは承認付き本番権限
法務Agentは限定資料だけ参照

Claude CodeのSubagentは、それぞれ独立したContext window、専用System prompt、特定Tool access、独立Permissionsを持てます。

Manager型とHandoff型を使い分ける

Manager型では、中央Agentが専門AgentをToolのように呼び、最終判断を保持します。

Handoff型では、処理の主導権を別Agentへ渡します。

OpenAI Agents SDKでは、AgentをToolとして呼ぶ構成とHandoffで主導権を移す構成が区別されています。

中央で文脈を統合する必要があるならManager型、専門Agentが後続の会話や処理まで引き継ぐならHandoff型が候補になります。

共有Stateと成果物の契約を定義する

Agent間で自然文だけを渡すと、情報が欠落します。

次を決めます。

入力Schema
出力Schema
State更新権限
Artifact名
完了状態
Error
Handoff条件
再実行条件

Agentを増やすほどTestも増える

個々のAgentが正しくても、連携で失敗することがあります。

誤ったAgentへ渡す
同じ仕事を複数Agentが行う
重要情報が引き継がれない
権限の強いAgentへ不要なHandoffをする
Agent間を循環し続ける

個別Testだけでなく、連携Testが必要です。

ケース：Webサイト修正をAIエージェントで安全に実行する

ここまでの設計を、Webサイト修正へ当てはめます。

Webサイト修正は、Agentがファイルを読み、コードを書き、Testし、Previewを作るため、ハーネスの要素を具体的に確認できます。

危険なのは、依頼から本番反映までを一つにまとめる構成

例えば次の構成です。

修正依頼
→ AIへ本番RepositoryとDeploy権限を渡す
→ AIが実装
→ AIがCommit
→ AIがDeploy

速く見えますが、問題があります。

要件の誤解を途中で止められない
対象外ファイルを変更できる
Test失敗のままDeployできる
Diffを確認できない
本番Credentialへアクセスできる
失敗時のRollback条件がない
誰が承認したか残らない

最初に要件・対象範囲・Done whenを固定する

入力は次です。

対象ページ
修正目的
Design原本
対応画面幅
必須機能
既存機能
変更禁止箇所
Test条件
完了条件
本番反映可否

不明点が結果を大きく変える場合は、実装前に質問させます。

作業用BranchとSandboxへ隔離する

Agentには、本番Branchへ直接書き込ませません。

作業用Branch
限定ディレクトリ
Test用環境変数
Sandbox
Preview環境

を使います。

本番Credentialは渡しません。

計画を先に作り、人間が範囲を確認する

Agentは、修正対象、変更予定ファイル、Test方法を計画します。

人間は次を確認します。

要件を理解しているか
変更範囲が広すぎないか
既存機能への影響
不要な依存追加
Test方針
Designとの対応

計画承認後に実装へ進みます。

実装後は複数の方法で検証する

最低限、次を行います。

Lint
Unit test
Integration test
Build
Browser Preview
Screenshot
Responsive確認
Console error
Diff
AI Review

Testの種類はプロジェクトに応じて選びます。

人間は、最終成果とリスクを確認する

人間へ提示するのは次です。

変更概要
対象ファイル
Diff
Test結果
Preview
Screenshot比較
未解決事項
既知のリスク
Rollback方法

承認後にCommit・Pull Requestへ進みます。

Deployは別の承認付き工程にする

コード承認と本番Deploy承認を分ける場合があります。

本番反映後はLive環境を確認します。

表示
主要操作
Error
Performance
既存機能

問題があれば、事前に決めた版へRollbackします。

実務テンプレート：AIハーネス設計キャンバス

設計済みの業務フローから一つ選び、次を整理してください。

対象業務：

1. Goal・Specification
目的：
対象範囲：
対象外：
入力：
成果物：
完了条件：
停止条件：

2. Model・Routing
計画用：
実行用：
検証用：
Fallback：
選択理由：
速度上限：
コスト上限：

3. Context・Knowledge
常時参照：
案件固有：
今回だけ：
正式資料：
旧版：
参照禁止：
最新性確認：
取得方法：

4. Instructions・Skills・Rules
Prompt：
Skill：
Rule：
Command：
Hook・Callback：
禁止事項：
変更管理：

5. Tools・API・MCP
Tool名：
目的：
使用条件：
使用禁止条件：
Read：
Write：
外部操作：
Draft／Publish分離：
入力Schema：
出力Schema：
Error：
副作用：
Timeout：

6. Session・State・Memory・Artifacts
Session単位：
業務State：
現在位置：
Checkpoint：
確定情報：
一時情報：
Memory：
Artifact：
再開方法：
保持期限：

7. Permissions・Secrets・Sandbox
作業領域：
ファイルRead：
ファイルWrite：
Shell：
Network：
外部サービス：
Secrets：
本番権限：
Sandbox：
承認者：

8. Human-in-the-loop・Guardrails
入力Guardrail：
出力Guardrail：
Tool Guardrail：
承認対象：
承認者：
提示情報：
判断基準：
承認期限：
差し戻し：
中止：
再開地点：

9. Trace・Logs・Tests
Trace ID：
記録するSpan：
記録しない情報：
Masking：
Log：
Test：
Diff：
Preview：
Screenshot：
保存期間：
閲覧権限：

10. Recovery・Fallback・Change Management
一時的失敗：
恒久的失敗：
Retry対象：
Retry回数：
待機間隔：
冪等性Key：
Checkpoint：
再開地点：
Fallback：
手動復帰：
Rollback：
Model版：
Prompt版：
Skill版：
Tool版：
Config版：
変更履歴：

11. Environments
開発環境：
検証環境：
本番環境：
Testデータ：
本番データ：
本番移行条件：

12. Agent構成
単一／複数：
分割理由：
Manager：
Subagent：
Handoff条件：
共有State：
入出力契約：

13. パイロット
対象：
対象者：
期間：
正常ケース：
例外ケース：
権限Test：
失敗Test：
中断・再開Test：
成功条件：
停止条件：
本番移行条件：

すべてを最初から埋める必要はありません。

最初は一つの業務、一つのAgent、少数のTool、Read-onlyから始めます。

そこから、必要性が検証された要素だけを追加します。

AIエージェント化しない方がよい場合もある

AIエージェントを作れることと、作るべきことは同じではありません。

処理が単純で、通常の自動化で十分

入力とルールが固定され、例外が少ないなら、通常のプログラムやRPAの方が安定し、安価で、Testしやすい場合があります。

正解条件を定義できない

完了条件も評価方法もなく、結果の良否を判断できない業務をAgentへ任せるべきではありません。

必要データへ安全にアクセスできない

機密情報、個人情報、権限が整理されていない場合、Agent接続より先にデータ管理を整えます。

外部操作の失敗を取り消せない

誤送信、誤課金、誤削除などの影響を限定できず、承認も実装できない場合は、自動実行へ進みません。

実行を観測できない

何を読んで、何を判断し、どのToolを使ったか分からない構成では、障害調査も改善もできません。

手動Fallbackがない

Agentが停止すると業務全体が止まる場合、先に手動復帰を設計します。

維持・Testする担当者がいない

Agentは作って終わりではありません。

モデル、Tool、API、業務、データは変わります。

保守担当者がいない場合は、構成を小さくする必要があります。

マルチエージェント化が目的になっている

複数Agentを使うこと自体は成果ではありません。

Context、権限、責任を分ける理由がないなら、一つのAgentや通常ワークフローを優先します。

フェーズ10の到達条件

次を満たせれば、フェーズ10の実践が進んでいると判断できます。

GoalとDone whenが明確
対象範囲と対象外が明確
モデル選択理由を説明できる
Context・Session・State・Memory・Artifactを分けている
Prompt・Rule・Skill・Testを分けている
Toolの目的、入力、出力、副作用が明確
Read／Writeを分けている
Draft／Publishを分けている
MCP・APIの接続目的が明確
不要なToolを見せていない
最小権限で動く
Secretsを安全に管理している
Sandbox、開発、検証、本番を分けている
Human-in-the-loopとGuardrailを使い分けている
承認状態と再開地点がある
Trace、Log、Diff、Test、Previewで検証できる
機微情報を記録しすぎていない
一時的失敗と恒久的失敗を区別している
Retry上限がある
二重処理を防げる
中断後に再開できる
Fallbackと手動復帰がある
Rollback可能性を把握している
単一・複数Agentの選択理由がある
別担当者が運用・復旧できる
技術構成が業務目的へ接続している

最も重要なのは、Agentがどれほど多くのことを一人で行えるかではありません。

何を行い、何を行わず、何を確認し、失敗したらどこで止まり、どこから戻るかを説明できることです。

次フェーズでは、作った基盤を継続的に評価・統制する

フェーズ10では、AIシステムを観測、Test、停止、復旧できる状態へしました。

しかし、公開前のTestに通っただけで、将来も品質が保たれるとは限りません。

次のような変化があります。

モデルが更新される
PromptやSkillが変わる
ToolやAPIが変わる
利用者が増える
入力データが変わる
費用が増える
新しい失敗が起きる
規程や法令が変わる
業務目的が変わる

そこで必要になるのが、継続的な評価・運用・ガバナンスです。

Golden Dataset
Evals
回帰Test
本番監視
Error分類
SLO
インシデント対応
変更管理
利用規程
監査
廃止条件

これがフェーズ11「評価・運用・ガバナンス」です。

フェーズ10で作るTrace、Test、Version、Logは、フェーズ11で継続管理するための土台になります。

まとめ：モデルはエンジンであり、仕事を完了させる仕組みではない

高性能なモデルは、複雑な推論、Tool選択、コード生成、長文理解を改善します。

しかし、モデル単体では次を決められません。

何を正式な情報とするか
どのToolを使ってよいか
どこまで権限を与えるか
どの操作に承認が必要か
何をもって完了とするか
何をTestするか
何をTraceへ残すか
失敗時にどこから戻るか
二重処理をどう防ぐか
本番へ反映してよいか

これらを結ぶのがハーネスです。

最初から巨大な基盤を作る必要はありません。

一つの業務、一つのAgent、少数のTool、Read-onlyから始めます。

Sandboxや作業用環境で試し、TestとDiffで確認し、人間承認を通してから限定的なWriteへ進む。

失敗を記録し、再開と復旧を試し、必要性が確認できた要素だけを追加する。

モデルはエンジンです。ハーネスは、そのエンジンが目的地へ安全に到達するための操縦系、計器、制限、整備手順です。

AIエージェントを実務で使えるかどうかは、モデルがどれほど賢いかだけではなく、周囲の実行設計をどこまで具体化できたかで決まります。

プロンプトから、コンテキスト、Tool、状態、権限、評価、ハーネスへ設計対象が広がった背景はこちらで整理しています。

同じ指示や失敗を、Rules、Skills、Tests、Hooksなどの再利用可能な仕組みへ変える方法はこちらで解説しています。

特定モデルへ依存せず、業務、評価基準、判断履歴、権限などを企業のAI資産として持つ考え方はこちらで詳しく考察しています。

企業で実行する場合

この記事で扱ったAIハーネスや実行基盤を、自社の業務フロー、AIエージェント開発、Codex・Claude Code活用、外部サービス連携、導入後の改善運用へ落とし込みたい場合は、支援内容を以下の記事にまとめています。

生成AIを導入した。でも、業務は変わらなかった。そんな企業へ研修から業務設計・開発・改善運用まで支援します

AI活用成熟度12フェーズの記事一覧

出典・参考資料

OpenAI Agents SDK — Agents
OpenAI Agents SDK — Human-in-the-loop
OpenAI Agents SDK — Tracing
OpenAI Agents SDK — Guardrails
OpenAI Agents SDK — MCP
OpenAI Agents SDK — Sandbox Agents
Anthropic — Claude Agent SDK
Anthropic — Claude Code Subagents
Anthropic — Claude Code MCP
Google Agent Development Kit — Sessions, State and Memory
Google Agent Development Kit — Artifacts
Model Context Protocol — Specification 2025-11-25
Model Context Protocol — Tools