implementing-agent-modes

Agent 模式

請參考以下步驟來規劃或實現新模式。模式是一種管理 agent 上下文（context）的方式，能針對特定產品、使用場景、JTBD（待辦任務）等注入相關的工具、提示詞（prompts）與模式相關行為。Agent 具備 switch_mode 工具，可自動切換至另一個模式，這可能會變更工具、提示詞與可執行檔（executables），同時保留當前的上下文。先前建立的部分工具具有上下文依賴性（contextual），代表它們只會被注入到前端的特定頁面中。而模式改變了這種做法，在模式上下文內始終包含所需的工具。

確定模式名稱

檢視 ee/hogai/core/agent_modes/presets 目錄，確認是否已有符合使用者意圖的模式。若想建立新模式，應將其範圍限定在 PostHog 產品（如 Product analytics）、產品領域（如 SQL）或 agent（如 Instrumentation agent）。

（選填）在 schema 中建立新模式

在 frontend/src/queries/schema/schema-assistant-messages.ts 中新增 AgentMode，並使用以下命令重新產生 schema：

hogli build:schema

或者，也可以使用此命令：

pnpm run schema:build

建立或更新模式的骨架

一個模式通常至少包含以下兩項：

• 一個 AgentToolkit：公開特定於該模式的工具，以及 todo 工具的軌跡範例（trajectory examples）。
• 一個 AgentModeDefinition：包含 AgentMode、始終注入 agent 上下文視窗（context window）的模式描述，以及 toolkit 和 executables 的類別（classes）。

注意：只有當使用者需要修改提示詞、該模式的行為或執行迴圈（execution loop）本身時，才需要建立新的 executable。

加入工具至模式中

相關工具可能部位於 ee/hogai/tools 或 products/<product_name>/backend/max_tools。有些工具會始終注入到上下文中（例如 read_data 工具），但其他所有工具都應該特定於該模式。

在將工具加入 toolkit 之前，請先確認這些工具是否有相依性（例如實驗依賴 feature flag 的建立）。如果存在相依性，請先與使用者確認是否要把多個模式合併為單一模式。若使用者不想合併，請確保後續加入明確說明模式切換與工具選擇的軌跡範例。

你還應該驗證這些工具是否為「後端優先」（backend-first）。如果工具僅在前端套用變更，而未將適當的上下文傳回對話中，你應該提出將其轉為後端優先的方案，以便 agent 擁有正確的上下文。

檢視預設 Toolkit

若新模式包含新的 Django models，應檢視 read_data、search 及 list_data 等工具是否具備檢索這些 model 的功能。若不支援這些 model，則應使用或實現 ee/hogai/context/... 中現有的上下文提供者（context providers）。

撰寫類 JTBD 軌跡範例

更新 AgentToolkit 以包含軌跡範例（trajectory examples）。這些範例應採用 JTBD 風格，展示 agent 如何搭配可用工具來完成典型任務。可參考 Product analytics preset 作為示範。

實現前端

更新 max-constants.tsx 以引入新工具，並將該模式加入模式選擇器中。你可能還需要建立新的 UI 元素來展示工具輸出的資料。

範例

假設你更新了 Error tracking 工具以列出 issue。以前它是一個僅更新篩選器（filters）的前端工具，但現在它會直接輸出錯誤追蹤的 issue。雖然 agent 擁有所需上下文，但使用者也需要以人類易讀的方式查看這些 issue。在此情況下，你應該設計並實現一個新的元件來顯示該工具的輸出。

加入 Feature Flag

所有新模式都必須加上 feature flag 控管。範例：

    @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

如果你建立了新工具，請確保正確設定 feature flag：

1. 當 feature flag 啟用時，正在被遷移的舊工具不應可用。
2. 新工具應僅在 feature flag 啟用時可用。

實現並更新測試

你應該測試新工具、preset、executable，並可選擇實現 evals（評估測試）。