implementing-agent-modes

エージェントモード

以下の手順を使用して、新しいモードを計画または実装してください。モードとは、エージェントのコンテキストを管理し、プロダクト、ユースケース、JTBD などに関連するツール、プロンプト、モード関連の動作を注入する方法です。エージェントは switch_mode ツールを持っており、これによって自身を別のモードに切り替えることができます。これにより、現在のコンテキストを保持したまま、ツール、プロンプト、実行可能ファイルが変更される場合があります。以前に作成されたツールの中には、コンテキスト依存のものがあります。つまり、フロントエンドの特定のページで注入されるものです。モードはアプローチを変更し、常にモードのコンテキスト内にツールを持ちます。

モード名を決定する

ee/hogai/core/agent_modes/presets ディレクトリを調べ、ユーザーの意図に一致するモードがすでに存在するかどうかを確認してください。新しいモードを作成する場合は、PostHog のプロダクト (Product analytics)、プロダクト領域 (SQL)、またはエージェント (Instrumentation agent) によってスコープを設定する必要があります。

(オプション) スキーマに新しいモードを作成する

frontend/src/queries/schema/schema-assistant-messages.ts に新しい AgentMode を追加し、以下を使用してスキーマを再生成します。

hogli build:schema

または、次のコマンドを使用することもできます。

pnpm run schema:build

モードのスキャフォールディングを作成または更新する

モードには通常、少なくとも次の 2 つを含める必要があります。

• モード固有のツールを公開する AgentToolkit と、todo ツール用のトラジェクトリ例。
• AgentMode、エージェントのコンテキストウィンドウに常に注入されるモードの説明、およびツールキットと実行可能ファイルのクラスを含む AgentModeDefinition。

注: 新しい実行可能ファイルは、ユーザーがそのモードのプロンプト、動作、または実行ループ自体を変更する必要がある場合にのみ作成してください。

モードにツールを追加する

関連するツールは ee/hogai/tools または products/<product_name>/backend/max_tools にある場合があります。read_data ツールのように常にコンテキストに注入されるツールのセットがありますが、それ以外のすべてのツールはモード固有であるべきです。

ツールをツールキットに追加する前に、それらのツールにツール依存関係があるかどうかを判断してください。依存関係がある場合 (例えば、実験がフィーチャーフラグの作成に依存する場合)、ユーザーに戻って、モードを 1 つに統合したいかどうかを確認してください。統合したくない場合は、後でモードの切り替えとツールの選択を明確に説明するトラジェクトリ例を必ず追加してください。

また、ツールがバックエンドファーストであることも確認する必要があります。ツールが適切なコンテキストを会話に返さずにフロントエンドの変更を適用する場合は、エージェントが正しいコンテキストを持てるように、バックエンドファーストにする方法を提案してください。

デフォルトのツールキットを確認する

新しいモードに新しい Django モデルが含まれる場合は、read_data、search、list_data ツールにそのモデルを取得する機能があるかどうかを確認してください。これらのモデルをサポートしていない場合は、ee/hogai/context/... で利用可能なコンテキストプロバイダーのいずれかを使用または実装してください。

JTBD 風のトラジェクトリ例を書く

AgentToolkit を更新して、トラジェクトリ例を含めてください。これらは、利用可能なツールを使用してエージェントが典型的なタスクをどのように達成すべきかを示す JTBD スタイルの例であるべきです。参考として Product analytics のプリセットを確認してください。

フロントエンドを実装する

max-constants.tsx を更新して新しいツールを含め、モードセレクターにモードを追加してください。また、ツールからのデータを表示するための新しい UI 要素を作成する必要がある場合もあります。

例

Error tracking ツールを更新してイシューを一覧表示するとします。以前はフィルターを更新するだけのフロントエンドツールでしたが、今では error tracking のイシューを出力します。エージェントには必要なコンテキストがありますが、ユーザーもイシューを人間が読める形で見る必要があります。この場合は、ツールの出力を表示する新しいコンポーネントを設計および実装してください。

フィーチャーフラグを追加する

すべての新しいモードはフィーチャーフラグで管理する必要があります。例:

    @property
    def mode_registry(self) -> dict[AgentMode, AgentModeDefinition]:
        registry = dict(DEFAULT_CHAT_AGENT_MODE_REGISTRY)
        if has_error_tracking_mode_feature_flag(self._team, self._user):
            registry[AgentMode.ERROR_TRACKING] = error_tracking_agent
        return registry

新しいツールを作成した場合は、それらを正しくフィーチャーフラグで管理してください。

1. 移行中の古いツールは、フィーチャーフラグが有効な場合は利用できないようにする必要があります。
2. 新しいツールは、フィーチャーフラグが有効な場合にのみ利用できるようにする必要があります。

テストの実装と更新

新しいツール、プリセット、実行ファイルをテストし、必要に応じて評価（eval）を実装してください。