agent-builder

エージェントビルダー

カスタマーサービス、調査、運用、クリエイティブ業務、または専門的なビジネスプロセスなど、あらゆる領域向けの AI エージェントを構築します。

適用範囲

アーキテクチャとオーケストレーションに関するガイダンスは、プロバイダーに依存しないものとして扱ってください。同梱されている Python のスターターコードは、現在 Anthropic SDK と Anthropic のモデル設定を使用しています。別のプロバイダーを使用する場合は、その実装レイヤーを適宜変更してください。サンプルのクライアントを、必須のエージェントアーキテクチャだと誤解しないでください。

基本となる考え方

モデルはすでにエージェントとして動く方法を知っています。あなたの仕事は、モデルの邪魔をしないことです。

エージェントに複雑なエンジニアリングは必要ありません。モデルに行動を促すシンプルなループです。

LOOP:
  Model sees: context + available capabilities
  Model decides: act or respond
  If act: execute capability, add result, continue
  If respond: return to user

これだけです。 魔法はコードではなく、モデルにあります。コードは、モデルが行動できる機会を提供するだけです。

3 つの要素

1. 能力（何ができますか？）

エージェントが実行できる基本的なアクションです。検索、読み取り、作成、送信、問い合わせ、変更などがあります。

設計原則：まずは 3～5 個の能力から始めます。能力がないためにエージェントが繰り返し失敗する場合にのみ、追加してください。

2. 知識（何を知っていますか？）

必要に応じて与える専門知識です。ポリシー、ワークフロー、ベストプラクティス、スキーマなどがあります。

設計原則：知識は利用可能にしますが、必須にはしません。最初から読み込むのではなく、関連する場合に読み込みます。

3. コンテキスト（何が起きましたか？）

会話の履歴です。アクションをつなぎ、一貫した振る舞いを生み出します。

設計原則：コンテキストは貴重です。ノイズの多いサブタスクは切り分けます。冗長な出力は短縮します。明瞭さを保ちます。

エージェント設計の考え方

構築する前に、以下を把握してください。

• 目的：このエージェントは何を達成すべきですか？
• 領域：どのような環境で動作しますか？（カスタマーサービス、調査、運用、クリエイティブ業務など）
• 能力：不可欠なアクションはどの 3～5 個ですか？
• 知識：どのような専門知識にアクセスする必要がありますか？
• 信頼：どのような判断をモデルに委ねられますか？

重要：モデルを信頼してください。過剰に設計しないでください。ワークフローをあらかじめ細かく指定しないでください。能力を与え、モデルに推論させてください。

段階的な複雑化

まずはシンプルに始めます。実際の利用によって必要性が明らかになった場合にのみ、複雑さを加えてください。

レベル	追加するもの	追加するタイミング
基本	3～5 個の能力	常にここから始めます
計画	進捗の追跡	複数ステップのタスクで一貫性が失われる場合
サブエージェント	分離された子エージェント	探索によってコンテキストが乱される場合
スキル	必要に応じて読み込む知識	領域の専門知識が必要な場合

ほとんどのエージェントは、レベル 2 を超える必要はありません。

領域ごとの例

ビジネス：CRM への問い合わせ、メール、カレンダー、承認
調査：データベース検索、ドキュメント分析、引用
運用：監視、チケット、通知、エスカレーション
クリエイティブ：アセットの生成、編集、コラボレーション、レビュー

このパターンは普遍的です。変わるのは能力だけです。

主な原則

1. モデルそのものがエージェントです - コードはループを実行するだけです
2. 能力が可能性を広げます - 何ができるか
3. 知識が実行を支えます - どうすればできるかを知っていること
4. 制約が焦点を絞ります - 制限が明瞭さを生み出します
5. 信頼が自由をもたらします - モデルに推論させます
6. 反復によって必要性が明らかになります - 最小限から始め、利用状況に応じて進化させます

アンチパターン

パターン	問題	解決策
過剰な設計	必要になる前に複雑になる	シンプルに始める
能力が多すぎる	モデルが混乱する	まずは 3～5 個にする
硬直したワークフロー	適応できない	モデルに判断させる
最初から知識を詰め込む	コンテキストが肥大化する	必要に応じて読み込む
細かく管理しすぎる	知性を活かせない	モデルを信頼する

リソースの使い分け

現在のタスクに必要なものだけを読み込みます。

ユーザーのニーズ	リソース	読み込まない場合
アーキテクチャを理解または議論する	references/agent-philosophy.md	ユーザーが実行可能なスターターコードだけを必要としている場合
最小限の完全なループを確認する	references/minimal-agent.py	タスクが概念的なもの、またはプロバイダーに依存しない場合
個々の機能を追加または調整する	references/tool-templates.py	実装が求められていない場合
コンテキストを分離した子エージェントを設計する	references/subagent-pattern.py	単一エージェントのループで十分な場合
ローカルの Python スタータープロジェクトを生成する	scripts/init_agent.py	ユーザーが設計のアドバイスだけを求めている場合

Python のリソースは学習を目的とした例であり、セキュリティ境界ではありません。シェル機能の使用には、デフォルトでユーザーの承認が必要です。本番システムでは、脅威モデルに応じた隔離、最小権限、監査ログ、ポリシーも必要です。

エージェントの考え方

「システムに X を実行させるには？」から
「モデルが X を実行できるようにするには？」へ

「このタスクのワークフローは？」から
「これを達成するには、どのような機能が役立つか？」へ

最良のエージェントコードは、驚くほど単純です。シンプルなループ。明確な機能。整理されたコンテキスト。魔法はコードの中にありません。

モデルに機能と知識を与え、あとはモデルが解決すると信頼してください。