1. ローカルのデモで何を確認できるか
ローカルで一度動いたときに確認できるのは、その実行が成功したことまでだ。本番投入前には、継続運用、同時実行、上流障害やモデル更新への対応、中断後の復旧と状態の整合性も確認する。実行し、記録し、検証と評価を行い、原因を特定して改善する。ここでは評価、可観測性、コスト、基盤、要件の実現を扱う。
2. 四つの層を評価する
- モデル出力。理解、推論、構造化出力の品質。
- ツール呼び出し。選択、引数、認可、エラー対応。
- ワークフロー。完了、一時停止、失敗、復旧。
- 業務結果。依頼されたタスクが実際に完了したか。
Coding Agent が立派な説明を出しても、コードが変わっていなければ修正は完了していない。
3. 正常系と異常系を含む Golden Set
- Coding Agent。リポジトリのコミットを固定し、元の依頼、編集範囲、禁止事項、合格必須のテスト、付与した権限、期待結果を記録する。
- RAG。質問、正解の根拠、文書の版、アクセス権、期待する引用、回答を控える条件を固定する。
- 異常系。タイムアウト、権限拒否、空の結果、データの矛盾、権限取り消し、中断、プロンプトインジェクション、モデルの挙動変化を含める。
セキュリティ違反は個別に不合格とし、平均点で相殺しない。
4. Trace で何を追跡するか
どんなコンテキストを使い、検索が何を返し、選んだツールが適切だったかを調べる。引数の検証、認可、実行の成否、状態の変化をたどり、最終結果がどう生成され、どう確かめられたかを確認する。Trace でこれらをたどれるようにする。
trace_id、user_id、tenant_id、session_id、task_id、run_id に加え、モデル、プロンプト、ツールの版、検索候補、トークン数、引数の要約、承認、状態遷移、結果への参照、エラー、所要時間、コストを記録する。ログをマスキングし、秘密情報、機密文書の全文、モデル内部の推論を入れない。必要な大きい成果物はアクセス制御されたオブジェクトストレージへ置き、Trace には参照だけを残す。OpenTelemetry の Trace
5. Replay で変更箇所を切り分ける
挙動の変化がモデル、プロンプト、検索、ツールスキーマ、ポリシー、状態のどこから来たか調べるには、ツール出力を固定し、モデルまたはポリシーのノードを再実行する。実ツールを呼び直すとデータが変わっていたり、副作用が重複したりする。全工程の Replay にはサンドボックスと固定データを使う。
6. 処理経路に沿って障害を調べる
入力、検索、コンテキスト、モデル、ツール、状態、表示の順に追い、段階ごとの指標を残す。文書が取れなければ解析、分割、クエリ、インデックスを調べる。検索できたがコンテキストに入らなければ選択と予算を調べる。根拠が入っていても誤答する場合は、モデル、事実の競合、制約を確認する。修正した障害を Golden Set に追加する。
7. 成功タスク当たりのコストを測る
モデルを10回呼ぶ場合と1回呼ぶ場合は、業務タスクを1件成功させる実コストで比べる。入力と出力のトークン、モデル呼び出し、キャッシュヒット率、ツール呼び出し回数、再試行回数、成功率、人への引き継ぎ率、総費用を記録し、タスク、モデル、ステップ別に集計する。
- コンテキストの重複を除き、要約とオンデマンド読み込みを使う。
- ツールスキーマは必要なものだけ読み込む。
- 単純な分類や書き換えは低コストのモデル、複雑なタスクは高性能のモデルへ送る。
- 埋め込み、解析結果、決定的なツールの実行結果をキャッシュする。
- ステップ、出力量、再試行の上限を設ける。
- リアルタイム性が不要な処理はバッチ化する。
コストを下げるときは遅延と完了率も確認する。
8. ストレージの責務を分ける
- PostgreSQL。ユーザー、テナント、セッション、タスク、承認、ツール呼び出し、規則、監査の正本。
- Redis。一時キャッシュ、ウィンドウ、レート制限カウンター、通知、リース、重複排除。
- Elasticsearch。転置インデックス、厳密なキーワード検索、絞り込み。
- Milvus または pgvector。埋め込みと検索用メタデータ。
- MinIO などのオブジェクトストレージ。原本、解析結果、大きなツール出力、報告書、不変のスナップショット。
業務上の事実は正本のデータベースに残し、最終的な認可は業務システムで確認する。記録をテナント、ユーザー、版、タスクにひも付ける。
9. 長時間タスクをスケジュールする
実行には数分以上かかることがある。HTTP リクエスト内でモデル、文書解析、外部ツールを待つと、タイムアウトやサービス資源の長時間占有につながる。たとえば API がタスクを PostgreSQL に書き込み、キューが Worker に通知し、Worker が更新した状態を SSE でクライアントに送る。キューは非同期化、負荷の平準化、スケジューリング、再試行、複数 Worker への配信を担う。タスク状態は別の状態機械が管理する。
少なくとも1回の配信を採用する場合、コンシューマーはイベント ID またはステップ ID で重複を排除する。Transactional Outbox はタスク本体と未送信イベントを同じトランザクションに書き込み、別のパブリッシャーがイベントを送る。AWS の Transactional Outbox 解説
10. SSE の切断後に進捗を復元する
SSE ではトークン、ツールの開始と終了、承認待ち、進捗、最終結果を送れる。イベントをセッション、実行、イベント ID にひも付け、増加する連番を持たせる。切断後はクライアントが最後に確認した連番の次から再開し、必要であれば先に正本のスナップショットを取り、新しいイベントを適用する。ストリーミング中のトークンは一時的でよい。タスク状態とツール実行記録はサーバーを正本とする。WHATWG の SSE 仕様
11. asyncio が役立つ並行処理
モデル API、データベース、HTTP、オブジェクトストレージ、キュー、ツールは I/O 待ちを伴うことが多い。async def 関数を呼ぶとコルーチンが返り、実行には await するか Task としてスケジュールする必要がある。非同期化しても自動的に並列化されたり、同時実行数が制限されたりはしない。セマフォや容量に上限のあるキューで制御する。
非同期 I/O には非同期インターフェース、ブロッキング I/O にはスレッド、CPU 負荷の高い処理にはプロセスや別サービスを使う。接続、読み取り、処理全体にタイムアウトを設け、キャンセル時にはリソースを解放する。ローカルコルーチンのキャンセルで外部の副作用は取り消されない。Python の asyncio ドキュメント
12. 5分が20分になったときの調査
API と Worker のキュー待ち、文書解析、検索、最初のトークンまでの時間、モデルの総処理時間、ツール、人の承認待ち、データベース、フロントエンドの購読を分けて測る。P50 と P95 を、キューの滞留、同時実行数、下流の制限、再試行による増幅、遅い SQL、ロック待ち、トークン増加、ツールの重複呼び出しと突き合わせる。
原稿の DevPilot 事例では、RLS が適用されたコマンド履歴クエリの走査範囲が広すぎた。対象テナントと認可済みの実行範囲に絞り、インデックスを調整したところ、合成負荷で単一クエリが 約0.6秒から約3ミリ秒 になった。原稿に記載された単一クエリの結果であり、プラットフォーム全体の P95 ではない。
13. 「もっと賢く」を検収可能な要件にする
ユーザー、タスク、使えるデータとツール、完了条件、禁止事項、誤りの代償、遅延とコストの上限を確認する。20〜50件の代表例で必要な結果、許容できる差、回答を控える条件を合意する。
最初は、検索して出典を添える最小の一連の機能を届ける。次に範囲を限定したツールを開放し、承認と再開を追加する。最後に複数 Agent や複雑なオーケストレーションを検討する。実際に失敗したケースは評価セットに追加し続ける。
14. 本番運用についての面接質問10項目
- 実際の利用者数とタスク量はどの程度か。
- タスク状態はどこに保存するか。
- ツール実行中に回線が切れたらどうするか。
- ユーザーが権限を取り消したとき、実行中のタスクをどう扱うか。
- 二重課金や二重実行をどう防ぐか。
- 実行をどう Replay するか。
- Golden Set をどう作るか。
- 失敗をどう追跡して切り分けるか。
- 成功タスク当たりのコストをどう測り、どう改善するか。
- モデル更新後の挙動の変化にどう対応するか。
何が起きたか、なぜ起きたか、どう再現したか、どう直したか、再発にどう備えたかを説明する。
15. 作れるシステムを具体的に説明する
Agent エンジニアリングの範囲は、アーキテクチャ、状態、ツール管理、認可と安全性、コンテキスト、検索、分散システム、評価と可観測性、コストと性能に及ぶ。モデルが操作を提案し、Harness が認可を確認して実行を管理する。基盤は結果の永続化、復旧、検証を可能にする。