agent-development

エージェント開発

概要

ツールを効果的に使い、メモリを管理し、複数ステップのタスクを計画し、他のエージェントと連携し、安全ガードレールの範囲内で動作する AI エージェントを設計・構築します。このスキルでは、アーキテクチャ設計から評価まで、エージェント開発のライフサイクル全体を扱い、観察可能で、テスト可能かつ安全なエージェントの動作に重点を置きます。

フェーズ 1：エージェント設計

1. エージェントの目的と範囲を定義します
2. 必要なツールと機能を特定します
3. メモリアーキテクチャを設計します（短期、長期）
4. エージェントループの構造を計画します（観察、思考、行動）
5. 安全境界とガードレールを定義します

停止 — 実装前にエージェント設計をユーザーに提示し、承認を得てください。

エージェントアーキテクチャの判断表

エージェントの種類	使用する場面	ループパターン	複雑さ
シングルターンのツール利用	ツール呼び出しを伴う単純なクエリ	リクエスト -> ツール -> 応答	低
ReAct エージェント	複数ステップの推論タスク	思考 -> アクション -> 観察 -> ループ	中
計画・実行型	依存関係のある複雑なタスク	計画 -> ステップを実行 -> 検証	中〜高
マルチエージェントオーケストレーター	並列または専門性の高いサブタスク	割り当て -> 収集 -> 統合	高
自律ループ（Ralph 型）	長時間にわたる反復的な開発	計画 -> 構築 -> 検証 -> 終了ゲート	高

フェーズ 2：実装

1. ツールのディスパッチ機能を備えたエージェントループを構築します
2. メモリ管理を実装します（コンテキストウィンドウ、永続化）
3. 計画とタスク分解のロジックを追加します
4. エラー回復と再試行パターンを統合します
5. 出力検証を実装します

停止 — 複雑さを追加する前に、エージェントループのスモークテストを実行してください。

ツール利用パターン

ツール定義のベストプラクティス

原則	ルール	例
明確な命名	動詞-名詞の形式	search_documents, create_file
詳細な説明	使用する場面と使用しない場面を含めます	"キーワード検索に使用します。意味的類似性の検索には使用しないでください。"
適切に型付けされたパラメーター	すべてのパラメーターに説明と例を付けます	query: string // "e.g., 'user authentication'"
予測可能な戻り値	ツール間で一貫した形式にします	常に { success, data, error } を返します
自己修正できるエラー	エージェントの回復を支援します	"日付の形式が無効です。ISO 8601 の形式が必要です：YYYY-MM-DD"

ツール選択戦略

Given a task:
1. Identify required information and actions
2. Map to available tools
3. Determine tool call order (dependencies)
4. Execute with result validation
5. Retry or try alternative tool on failure

ツール設計の原則

• 組み合わせ可能：複雑なタスクに組み合わせて使える小さなツールにします
• 冪等性：可能な限り、副作用なしで安全に再試行できるようにします
• 観察可能：成功を検証するために十分なコンテキストをエージェントに返します
• 制限付き：すべての操作にタイムアウトとサイズ制限を設けます
• 文書化：すべてのパラメーターと戻り値について説明します

メモリ管理

メモリの種類の判断表

種類	期間	ストレージ	用途
作業メモリ	現在のターン	コンテキストウィンドウ	アクティブな推論
短期メモリ	現在のセッション	コンテキスト内またはバッファー	最近の会話
長期メモリ	セッションをまたぐ	データベース／ファイル	学習したパターン、ユーザーの設定
エピソードメモリ	特定の出来事	インデックス付きストア	過去のタスクの結果
意味メモリ	知識	ベクトル DB	ドメイン知識の検索

コンテキストウィンドウ管理

Strategy: Sliding window with importance-based retention

1. Always retain: system prompt, tool definitions, current task
2. Summarize: older conversation turns into compressed summaries
3. Evict: least relevant context when approaching limit
4. Retrieve: pull relevant long-term memory on demand

Budget allocation:
  System prompt + tools: ~20%
  Current task context:  ~40%
  Conversation history:  ~25%
  Retrieved memory:      ~15%

メモリ更新のトリガー

トリガー	アクション
ユーザーによる訂正	学習したパターンを更新します
タスクの完了	結果とアプローチを保存します
エラーからの回復	失敗したことと成功したことを記録します
新しいドメイン知識	今後の検索に備えてインデックス化します

計画戦略

階層的なタスク分解

1. Break high-level goal into sub-goals
2. For each sub-goal, identify required actions
3. Order actions by dependencies
4. Execute with checkpoints between phases
5. Re-plan if intermediate results change the approach

ReAct パターン（推論 + 行動）

Thought: I need to find the user's recent orders to answer their question.
Action: search_orders(user_id="123", limit=5)
Observation: Found 5 orders, most recent is #456 from yesterday.
Thought: The user asked about order #456. I have the details now.
Action: respond with order details

計画・実行パターン

1. Create a complete plan before any action
2. Execute each step, checking preconditions
3. After each step, validate the result
4. If a step fails, re-plan from current state
5. Never modify the plan mid-step (finish or abort first)

リフレクションパターン

After completing a task:
1. Was the result correct?
2. Was the approach efficient?
3. What could be improved?
4. Should any memory be updated?

フェーズ 3：評価と安全性

1. テストシナリオを含む評価ハーネスを構築します
2. 正確性、効率性、安全性の指標を測定します
3. エッジケースと敵対的な入力をテストします
4. 監視とロギングを追加します
5. 暴走動作に対するサーキットブレーカーを実装します

停止 — デプロイ前に、すべての安全ガードレールをテストする必要があります。

マルチエージェントの連携

連携パターンの判断表

パターン	説明	使用する状況
オーケストレーター	中央のエージェントが専門エージェントに作業を委任します	明確なタスク階層がある場合
パイプライン	エージェントが順番に処理します	直線的なワークフローの場合
ディベート	エージェントが提案し、批評します	多様な視点が必要な場合
投票	複数のエージェントで多数決を行います	アプローチに不確実性がある場合
スーパーバイザー	1 つのエージェントが他のエージェントを監視します	安全性が重要なタスクの場合

通信プロトコル

Agent-to-Agent message:
{
  "from": "planner",
  "to": "executor",
  "type": "task_assignment",
  "content": { "task": "...", "context": "...", "constraints": "..." },
  "priority": "high",
  "deadline": "2025-01-15T10:00:00Z"
}

連携ルール

• 明確な所有権の境界を定義します
• エージェント間で構造化されたメッセージを使用します
• デッドロック検出を実装します
• エージェント間通信にタイムアウトを設定します
• デバッグ用に、エージェント間のすべてのメッセージをログに記録します

評価フレームワーク

指標の判断表

指標	測定内容	測定方法	目標
タスク成功率	正しく完了した件数 / 合計	自動評価 + 人間による評価	> 90%
効率性	最適な経路と比較したステップ数	ステップ数の比較	< 2x optimal
ツール精度	正しいツール呼び出し数 / 合計	ログ分析	> 95%
安全性	違反数 / インタラクションの合計	ガードレールのチェック	違反 0 件
レイテンシ	タスクの完了時間	実時間	< SLA
コスト	タスクごとのトークン使用量	API 使用状況の追跡	予算内

評価データセットの構造

{
  "test_cases": [
    {
      "id": "tc_001",
      "input": "Find all orders over $100 from last week",
      "expected_tools": ["search_orders"],
      "expected_output_contains": ["order_id", "amount"],
      "category": "retrieval",
      "difficulty": "easy"
    }
  ]
}

安全ガードレール

入力ガードレール

• プロンプトインジェクションの試みを検出して拒否します
• 処理前にすべてのユーザー入力を検証します
• ユーザー／セッションごとのリクエスト数を制限します
• 有害なリクエストをコンテンツフィルタリングします

出力ガードレール

• 実行前にツール呼び出しの引数を検証します
• 出力に機密情報（PII、秘密情報）が含まれていないか確認します
• 応答形式の制約を適用します
• ツール呼び出しの無限ループを防ぎます

運用ガードレール

• タスクごとのツール呼び出しの最大数（サーキットブレーカー）
• 応答ごとの最大トークン数
• タスク全体の実行時間のタイムアウト
• 信頼度が低い場合は人間にエスカレーションします
• すべての操作を監査ログに記録します

サーキットブレーカーのしきい値

条件	しきい値	アクション
タスクごとのツール呼び出しの最大数	20	実行を停止し、エラーを返します
連続エラーの最大数	3	停止してログに記録し、適切なエラーを返します
タスクの最大実行時間	5 minutes	タイムアウトし、部分的な結果を返します
生成トークンの最大数	10,000	生成を停止します
パターンの繰り返し	同一のエラーが 5 回	サーキットを開き、オペレーターに警告します

エージェントのプロンプトエンジニアリング

システムプロンプトの構造

1. Identity and purpose (who the agent is)
2. Available tools (what it can do)
3. Constraints (what it must not do)
4. Output format (how to respond)
5. Examples (few-shot demonstrations)
6. Error handling (what to do when stuck)

主要なプロンプトパターン

• スクラッチパッド：行動に移る前に、段階的に推論するよう促します
• 自己修正：「最初のアプローチがうまくいかない場合は、次を試してください……」
• 信頼度の調整：「確信がある場合にのみ続行してください」
• 段階的な縮退：「タスクを完了できない場合は、その理由を説明してください」

アンチパターン／よくある間違い

アンチパターン	なぜ問題なのか	代わりに行うこと
推論せずにツールを呼び出す	呼び出しを無駄にし、コンテキストを見落とします	ReAct パターンを使います（まず考えます）
最大反復回数の制限がない	無限ループやコストの急増につながります	サーキットブレーカーのしきい値を設定します
すべてのツール出力を信頼する	破損したデータが伝播します	ツールの結果を検証します
ツールの呼び出し順序をハードコードする	障害に対応できません	状態に応じてツールを動的に選択します
エラー回復戦略がない	最初の失敗でエージェントが行き詰まります	代替手段を用いた再試行を実装します
行動せずに謝罪する	ユーザーの時間を無駄にします	是正措置を講じてから報告します
単一のツールに過度に依存する	そのツールが失敗すると脆弱になります	フォールバック用のツールを用意します
評価フレームワークがない	品質の指標がないままリリースすることになります	デプロイ前に評価用ハーネスを構築します
コンテキストを無制限に増やす	コンテキストのあふれや品質の低下につながります	メモリ管理を実装します

統合ポイント

スキル	統合
mcp-builder	MCP サーバーはエージェント向けのツールを提供します
planning	エージェントの計画では、構造化された計画生成を使用します
autonomous-loop	Ralph 形式のループは、エージェントパターンの一種です
dispatching-parallel-agents	マルチエージェントの連携パターン
circuit-breaker	エージェントループの運用上の安全性
verification-before-completion	エージェント出力の検証
test-driven-development	エージェントのツール実装に対する TDD

スキルの種類

FLEXIBLE — エージェントのアーキテクチャ、メモリ戦略、連携パターンを、特定のユースケースに合わせて調整してください。本番環境で稼働するすべてのエージェントに、安全ガードレールと評価フレームワークを強く推奨します。