Use the steps below to plan or implement a new mode. A mode is a way to manage the context of the agent and inject tools, prompts, and mode-related behavior relevant to a product, use case, JTBD, etc. The agent has the tool that allows it to switch itself to another mode, which might change tools, prompt, and executables, preserving the current context. Some previously created tools are contextual, meaning they're injected on particular pages of the frontend. The modes change the approach and always have tools in the mode context.

Explore the directory and check if there are already modes that match the user's intent. If you want to create a new mode, you should scope it by a PostHog product (Product analytics), product area (SQL), or agent (Instrumentation agent).

Add a new AgentMode to and regenerate the schema using:

hogli build:schema

Alternatively, you may use this command:

pnpm run schema:build

A mode should typically contain at least two things:

Note: you should only create new executables if the user needs to modify the prompt, behavior of that mode, or the execution loop itself.

Relevant tools might be located in or . There is a set of tools that is always injected into the context, like the tool, but all other tools should be specific to the mode.

Before adding a tool to the toolkit, determine if those tools have tool dependencies. If there are dependencies (like an experiment depends on feature flag creation), loop back to the user to determine whether they want to merge modes into a single one. If they don't want to do that, make sure that you later add a trajectory example clearly explaining mode switching and tool selection.

You should also verify that the tools are backend-first. If tools apply frontend changes without passing proper context back to the conversation, you should propose a way to make them backend-first so the agent has the right context.

If the new mode contains new Django models, you should review whether the , , and tools have the functionality to retrieve the models. If they don't support these models, you should use or implement one of the context providers available in .

Update the AgentToolkit to include trajectory examples. These should be JTBD-style examples showing how the agent should achieve typical tasks with the available tools. Check the Product analytics preset for reference.

Update to include new tools and add the mode to the mode selector. You might also need to create new UI elements for displaying data from the tools.

Say you've updated the Error tracking tool to list issues. It used to be a frontend tool that only updated filters, but now it outputs error tracking issues. While the agent has the context it needs, the user also needs to see the issues in a human-readable way. In this case, you should design and implement a new component to display the tool's output.

All new modes must be feature-flagged. Example:

    @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

If you have created new tools, make sure you feature flag them correctly:

You should test new tools, presets, executables, and optionally implement evals.