implementing-agent-modes

Agent 模式（Agent modes）

按照以下步骤规划或实现一个新模式（Mode）。模式用于管理 Agent 的上下文，并按产品、使用场景、JTBD（待办任务）等维度注入相应的工具、Prompt 和模式专属行为。Agent 自带 switch_mode 工具，可以在保留当前上下文的前提下切换到另一个模式，从而变更可用工具、Prompt 和可执行文件（executables）。以往部分工具是基于上下文的（即仅在前端特定页面注入），而模式改变了这一机制，将工具直接锁定在模式上下文内。

确定模式名称

先探索 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

创建或更新模式的脚手架（Scaffolding）

一个模式通常应包含以下两部分：

• 一个 AgentToolkit：暴露出该模式专属的工具，以及为 todo 工具准备的轨迹示例（trajectory examples）。
• 一个 AgentModeDefinition：包含 AgentMode、始终注入 Agent 上下文窗口的模式描述（mode description），以及 Toolkit 和 executables 的类。

注意：只有当用户需要修改该模式的 Prompt、行为或执行循环本身时，才需要创建新的 executables。

向模式中添加工具

相关工具通常存放在 ee/hogai/tools 或 products/<product_name>/backend/max_tools 中。有一些通用工具（如 read_data）会自动注入上下文，但其他工具都应该归属于特定模式。

在将工具添加到 toolkit 之前，需先确认工具之间是否存在依赖关系。如果存在依赖（例如：实验功能依赖于 Feature Flag 的创建），需要与用户沟通，确认是否将多个模式合并为一个。如果用户不打算合并，请务必在后续添加轨迹示例，清晰解释模式切换和工具选择的过程。

此外还需确认工具是否遵循“后端优先（backend-first）”原则。如果某个工具直接修改了前端状态却没有将合适的上下文带回对话中，你需要提出改造方案使其变为后端优先，确保 Agent 能拿到正确的上下文。

审查默认 Toolkit

如果新模式引入了新的 Django 模型，应审查 read_data、search 和 list_data 等工具是否已具备检索这些模型的能力。如果尚不支持，应使用或实现 ee/hogai/context/... 中现有的上下文提供者（context providers）。

撰写 JTBD 式轨迹示例

更新 AgentToolkit，补充轨迹示例（trajectory examples）。这些示例应采用 JTBD（待办任务）视角，展示 Agent 如何配合现有工具完成典型任务。可参考 Product analytics 预设方案。

实现前端

更新 max-constants.tsx 以引入新工具，并将新模式添加到模式选择器中。如有必要，还需创建全新的 UI 组件来展示工具输出的数据。

示例

假设你更新了 Error tracking 工具，使其支持列出 Issue。以前它只是个单纯更新筛选条件的前端工具，而现在能直接输出错误追踪 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 开启时可用。

实现并更新测试

你需要对新工具、预设（presets）、executables 进行测试，并视情况编写 Eval 评测。