implementing-agent-modes

Guidelines for creating or updating a mode for the PostHog AI agent. A mode is a way to manage the agent's context by scoping which tools, prompts, and prompt injections apply and under what conditions, so the agent produces better results for a specific product, product area, or job-to-be-done. The agent can move between modes with its switch_mode tool, which swaps tools, prompt, and executables while preserving the current context. Because some tools are contextual (injected only on particular frontend pages), modes provide a consistent way to always carry the right tools in context.

The workflow walks through concrete steps in the PostHog codebase: exploring ee/hogai/core/agent_modes/presets to check for an existing matching mode; optionally adding a new AgentMode to the schema and regenerating it (hogli build:schema or pnpm run schema:build); building the mode scaffolding as an AgentToolkit (tools plus JTBD-style trajectory examples) and an AgentModeDefinition (the mode description injected into context, plus toolkit and executable classes); wiring in tools from ee/hogai/tools or products/<product_name>/backend/max_tools; and reviewing the default read_data, search, and list_data tools for any new Django models. It emphasizes checking tool dependencies, looping back to the user about merging modes when tools depend on each other, and keeping tools backend-first so the agent retains proper context.

Use it when planning or implementing a new agent mode, or updating an existing one. It also covers the frontend side, updating max-constants.tsx, adding the mode to the mode selector, and building UI to display tool output, and mandates that all new modes be feature-flagged, including guidance that migrated tools be hidden when a flag is active while new tools appear only when it is. The final step is implementing and updating tests for new tools, presets, and executables, with optional evals.