:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import asyncio
from collections.abc import Mapping, Sequence
from typing import Any, Literal, TypeVar, cast
from uuid import uuid4
import structlog
import posthoganalytics
from langchain_core.messages import (
AIMessage as LangchainAIMessage,
BaseMessage,
HumanMessage as LangchainHumanMessage,
ToolCall,
ToolMessage as LangchainToolMessage,
)
from langchain_core.runnables import RunnableConfig
from langgraph.errors import GraphInterrupt
from langgraph.types import Send
from opentelemetry import trace
from posthoganalytics import capture_exception
from pydantic import ValidationError
from posthog.schema import (
AgentMode,
AssistantMessage,
AssistantTool,
AssistantToolCall,
AssistantToolCallMessage,
ContextMessage,
FailureMessage,
HumanMessage,
)
from posthog.event_usage import groups
from posthog.llm.gateway_client import resolve_ai_gateway_config
from posthog.models import Team, User
from posthog.sync import database_sync_to_async
from ee.hogai.core.agent_modes.prompt_builder import AgentPromptBuilder
from ee.hogai.core.agent_modes.prompts import (
ROOT_CONVERSATION_SUMMARY_PROMPT,
ROOT_HARD_LIMIT_REACHED_PROMPT,
ROOT_TOOL_DOES_NOT_EXIST,
)
from ee.hogai.core.agent_modes.toolkit import AgentToolkitManager
from ee.hogai.core.executable import BaseAgentExecutable
from ee.hogai.llm import MaxChatAnthropic
from ee.hogai.tool import MaxTool, ToolMessagesArtifact
from ee.hogai.tool_errors import MaxToolError
from ee.hogai.utils.anthropic import add_cache_control, convert_to_anthropic_messages
from ee.hogai.utils.conversation_summarizer import AnthropicConversationSummarizer
from ee.hogai.utils.helpers import convert_tool_messages_to_dict, normalize_ai_message
from ee.hogai.utils.types import (
AssistantMessageUnion,
AssistantNodeName,
AssistantState,
PartialAssistantState,
ReplaceMessages,
)
from ee.hogai.utils.types.base import NodePath
from .compaction_manager import AnthropicConversationCompactionManager
RootMessageUnion = HumanMessage | AssistantMessage | FailureMessage | AssistantToolCallMessage | ContextMessage
T = TypeVar("T", RootMessageUnion, BaseMessage)
logger = structlog.get_logger(__name__)
_tracer = trace.get_tracer(__name__)
class BaseAgentLoopExecutable(BaseAgentExecutable[AssistantState, PartialAssistantState]):
def __init__(
self,
*,
team: Team,
user: User,
toolkit_manager_class: type[AgentToolkitManager],
node_path: tuple[NodePath, ...],
):
super().__init__(team, user, node_path)
self._toolkit_manager_class = toolkit_manager_class
class BaseAgentLoopRootExecutable(BaseAgentLoopExecutable):
def __init__(
self,
*,
team: Team,
user: User,
toolkit_manager_class: type[AgentToolkitManager],
prompt_builder_class: type[AgentPromptBuilder],
node_path: tuple[NodePath, ...],
):
super().__init__(team=team, user=user, toolkit_manager_class=toolkit_manager_class, node_path=node_path)
self._prompt_builder_class = prompt_builder_class
class AgentExecutable(BaseAgentLoopRootExecutable):
MAX_TOOL_CALLS = 24
"""
Determines the maximum number of tool calls allowed in a single generation.
"""
THINKING_CONFIG = {"type": "enabled", "budget_tokens": 10240}
"""
Determines the thinking configuration for the model.
"""
def __init__(
self,
*,
team: Team,
user: User,
toolkit_manager_class: type[AgentToolkitManager],
prompt_builder_class: type[AgentPromptBuilder],
node_path: tuple[NodePath, ...],
):
super().__init__(
team=team,
user=user,
toolkit_manager_class=toolkit_manager_class,
prompt_builder_class=prompt_builder_class,
node_path=node_path,
)
self._window_manager = AnthropicConversationCompactionManager()
async def arun(self, state: AssistantState, config: RunnableConfig) -> PartialAssistantState:
toolkit_manager = self._toolkit_manager_class(
team=self._team, user=self._user, context_manager=self.context_manager
)
prompt_builder = self._prompt_builder_class(
team=self._team, user=self._user, context_manager=self.context_manager
)
tools, system_prompts = await asyncio.gather(
*[toolkit_manager.get_tools(state, config), prompt_builder.get_prompts(state, config)]
)
tools = cast("list[MaxTool]", tools)
model = self._get_model(state, tools)
# Add context messages on start of the conversation.
messages_to_replace: Sequence[AssistantMessageUnion] = []
if self._is_first_turn(state) and (
updated_messages := await self.context_manager.get_state_messages_with_context(state)
):
messages_to_replace = updated_messages
# Calculate the initial window.
langchain_messages = self._construct_messages(
messages_to_replace or state.messages, state.root_conversation_start_id, state.root_tool_calls_count
)
window_id = state.root_conversation_start_id
start_id = state.start_id
# Summarize the conversation if it's too long.
current_token_count = await self._window_manager.calculate_token_count(
model, langchain_messages, tools=tools, thinking_config=self.THINKING_CONFIG
)
if current_token_count > self._window_manager.CONVERSATION_WINDOW_SIZE:
# Exclude the last message if it's the first turn.
messages_to_summarize = langchain_messages[:-1] if self._is_first_turn(state) else langchain_messages
summary = await AnthropicConversationSummarizer(
self._team,
self._user,
conversation_start_dt=state.start_dt,
).summarize(messages_to_summarize)
summary_message = ContextMessage(
content=ROOT_CONVERSATION_SUMMARY_PROMPT.format(summary=summary),
id=str(uuid4()),
)
# Insert the summary message before the last human message
insertion_result = self._window_manager.update_window(
messages_to_replace or state.messages,
summary_message,
state.agent_mode_or_default,
start_id=start_id,
window_start_id=window_id,
)
window_id = insertion_result.updated_window_start_id
start_id = insertion_result.updated_start_id
messages_to_replace = insertion_result.messages
# Update the window
langchain_messages = self._construct_messages(messages_to_replace, window_id, state.root_tool_calls_count)
system_prompts = cast(list[BaseMessage], system_prompts)
assert len(system_prompts) > 0
# Mark the longest default prefix as cacheable
add_cache_control(system_prompts[0], ttl="1h")
message = await model.ainvoke(system_prompts + langchain_messages, config)
generated_messages = self._process_output_message(message)
# Set new tool call count
tool_call_count = (state.root_tool_calls_count or 0) + 1 if generated_messages[-1].tool_calls else None
# Replace the messages with the new message window
new_messages: list[AssistantMessageUnion] | ReplaceMessages[AssistantMessageUnion]
if messages_to_replace:
new_messages = ReplaceMessages([*messages_to_replace, *generated_messages])
else:
new_messages = cast(list[AssistantMessageUnion], generated_messages)
# NOTE: We intentionally do NOT extract the mode from switch_mode tool calls here.
# The mode should only change AFTER the tools node validates and executes the tool.
# If we set agent_mode prematurely, the tools node will use the wrong mode_registry
# to validate the switch_mode call (e.g., trying to validate "plan" against the
# plan mode registry which doesn't have "plan" as a valid mode).
return PartialAssistantState(
messages=new_messages,
root_tool_calls_count=tool_call_count,
root_conversation_start_id=window_id,
start_id=start_id,
agent_mode=state.agent_mode_or_default,
)
def router(self, state: AssistantState):
last_message = state.messages[-1]
if not isinstance(last_message, AssistantMessage) or not last_message.tool_calls:
return AssistantNodeName.END
return [
Send(AssistantNodeName.ROOT_TOOLS, state.model_copy(update={"root_tool_call_id": tool_call.id}))
for tool_call in last_message.tool_calls
]
def _get_agent_mode_posthog_properties(self, state: AssistantState) -> dict[str, Any]:
"""Telemetry props so $ai_generation events can be scoped to a specific agent mode."""
supermode = state.supermode
supermode_value: str | None
if isinstance(supermode, AgentMode):
supermode_value = supermode.value
elif isinstance(supermode, str):
supermode_value = supermode
else:
supermode_value = None
return {
"agent_mode": state.agent_mode_or_default.value,
"supermode": supermode_value,
}
def _get_model(self, state: AssistantState, tools: list["MaxTool"]):
model_kwargs: dict[str, Any] = {
"model": "claude-sonnet-4-6",
"streaming": True,
"stream_usage": True,
"user": self._user,
"team": self._team,
"betas": [
"interleaved-thinking-2025-05-14",
"fine-grained-tool-streaming-2025-05-14",
],
"max_tokens": 16384,
"thinking": self.THINKING_CONFIG,
# langchain-anthropic 0.3.x doesn't have a first-class effort field;
# forward it via model_kwargs so the Anthropic API receives output_config.
"model_kwargs": {"output_config": {"effort": "medium"}},
"conversation_start_dt": state.start_dt,
"billable": True,
"posthog_properties": self._get_agent_mode_posthog_properties(state),
}
if resolve_ai_gateway_config() is not None:
base_model = MaxChatAnthropic(**model_kwargs)
else:
base_model = MaxChatAnthropic(**model_kwargs)
# The agent can operate in loops. Since insight building is an expensive operation, we want to limit a recursion depth.
# This will remove the functions, so the agent doesn't have any other option but to exit.
if self._is_hard_limit_reached(state.root_tool_calls_count):
return base_model
return base_model.bind_tools(tools, parallel_tool_calls=True)
def _construct_messages(
self,
messages: Sequence[AssistantMessageUnion],
window_start_id: str | None = None,
tool_calls_count: int | None = None,
) -> list[BaseMessage]:
conversation_window = self._window_manager.get_messages_in_window(messages, window_start_id)
# `assistant` messages must be contiguous with the respective `tool` messages.
tool_result_messages = self._get_tool_map(conversation_window)
# Convert to Anthropic messages
history = self._convert_to_langchain_messages(conversation_window, tool_result_messages)
# Force the agent to stop if the tool call limit is reached.
history = self._add_limit_message_if_reached(history, tool_calls_count)
# Append a single cache control to the last human message or last tool message,
# so we cache the full prefix of the conversation.
history = self._add_cache_control_to_last_message(history)
return history
def _filter_assistant_messages(self, messages: Sequence[AssistantMessageUnion]) -> Sequence[RootMessageUnion]:
"""Filter out messages that are not part of the assistant conversation."""
return [message for message in messages if isinstance(message, RootMessageUnion)]
def _get_messages_in_window(
self, messages: Sequence[AssistantMessageUnion], window_start_id: str | None = None
) -> Sequence[AssistantMessageUnion]:
"""Filter out messages that are not part of the conversation window."""
filtered_messages = self._filter_assistant_messages(messages)
return self._window_manager.get_messages_in_window(filtered_messages, window_start_id)
def _add_limit_message_if_reached(
self, messages: list[BaseMessage], tool_calls_count: int | None
) -> list[BaseMessage]:
"""Append a hard limit reached message if the tool calls count is reached."""
if self._is_hard_limit_reached(tool_calls_count):
return [*messages, LangchainHumanMessage(content=ROOT_HARD_LIMIT_REACHED_PROMPT)]
return messages
def _get_tool_map(self, messages: Sequence[AssistantMessageUnion]) -> Mapping[str, AssistantToolCallMessage]:
"""Get a map of tool call IDs to tool call messages."""
return convert_tool_messages_to_dict(messages)
def _convert_to_langchain_messages(
self,
messages: Sequence[AssistantMessageUnion],
tool_result_messages: Mapping[str, AssistantToolCallMessage],
) -> list[BaseMessage]:
"""Convert a conversation window to a list of Langchain messages."""
return convert_to_anthropic_messages(messages, tool_result_messages)
def _add_cache_control_to_last_message(self, messages: list[BaseMessage]) -> list[BaseMessage]:
"""Add cache control to the last message."""
for i in range(len(messages) - 1, -1, -1):
maybe_content_arr = messages[i].content
if (
isinstance(messages[i], LangchainHumanMessage | LangchainAIMessage)
and isinstance(maybe_content_arr, list)
and len(maybe_content_arr) > 0
and isinstance(maybe_content_arr[-1], dict)
):
maybe_content_arr[-1]["cache_control"] = {"type": "ephemeral"}
break
return messages
def _is_hard_limit_reached(self, tool_calls_count: int | None) -> bool:
return tool_calls_count is not None and tool_calls_count >= self.MAX_TOOL_CALLS
def _process_output_message(self, message: LangchainAIMessage) -> list[AssistantMessage]:
"""Process the output message."""
return normalize_ai_message(message)
class AgentToolsExecutable(BaseAgentLoopExecutable):
async def arun(self, state: AssistantState, config: RunnableConfig) -> PartialAssistantState:
resolved = self._resolve_tool_call(state)
if resolved is None:
return PartialAssistantState(root_tool_call_id=None)
tool_call_message, tool_call = resolved
tool = await self._find_tool(state, config, tool_call.name)
# If the tool doesn't exist, return the message to the agent
if not tool:
return self._tool_call_state(ROOT_TOOL_DOES_NOT_EXIST, tool_call.id)
# Tricky: set the node path associated with the tool call
tool.set_node_path(
(
*self.node_path[:-1],
NodePath(name=AssistantNodeName.ROOT_TOOLS, message_id=tool_call_message.id, tool_call_id=tool_call.id),
)
)
try:
result = await self._invoke_tool(tool, tool_call, config)
await self._capture_tool_executed(tool_call, config)
except MaxToolError as e:
return self._max_tool_error_state(e, tool_call, config)
except ValidationError as e:
logger.exception("Validation error calling tool", extra={"tool_name": tool_call.name, "error": str(e)})
capture_exception(
e, distinct_id=self._get_user_distinct_id(config), properties=self._get_debug_props(config)
)
return self._tool_call_state("There was a validation error calling the tool: " + str(e), tool_call.id)
except GraphInterrupt:
# GraphInterrupt is raised when a tool calls interrupt() for approval flow.
# Let it propagate up to be handled by LangGraph's interrupt
raise
except Exception as e:
logger.exception("Error calling tool", extra={"tool_name": tool_call.name, "error": str(e)})
capture_exception(
e, distinct_id=self._get_user_distinct_id(config), properties=self._get_debug_props(config)
)
return self._tool_call_state(
"The tool raised an internal error. Do not immediately retry the tool call and explain to the user what happened. If the user asks you to retry, you are allowed to do that.",
tool_call.id,
)
return await self._state_from_tool_result(result, tool_call, state, config)
def _resolve_tool_call(self, state: AssistantState) -> tuple[AssistantMessage, AssistantToolCall] | None:
tool_call_message = self._find_tool_call_message(state)
if not tool_call_message or not tool_call_message.id or not state.root_tool_call_id:
return None
# Find the current tool call in the message.
tool_call = next(
(tool_call for tool_call in tool_call_message.tool_calls or [] if tool_call.id == state.root_tool_call_id),
None,
)
if not tool_call:
return None
return tool_call_message, tool_call
def _find_tool_call_message(self, state: AssistantState) -> AssistantMessage | None:
last_message = state.messages[-1]
# Check if we're resuming from an interrupted approval flow
if isinstance(last_message, AssistantToolCallMessage) and state.root_tool_call_id:
return self._find_interrupted_tool_call_message(state)
if isinstance(last_message, AssistantMessage):
return last_message
return None
def _find_interrupted_tool_call_message(self, state: AssistantState) -> AssistantMessage | None:
# Look for the original AssistantMessage with the tool call
for msg in reversed(state.messages[:-1]):
if isinstance(msg, AssistantMessage) and msg.tool_calls:
if any(tc.id == state.root_tool_call_id for tc in msg.tool_calls):
return msg
return None
async def _find_tool(self, state: AssistantState, config: RunnableConfig, tool_name: str) -> MaxTool | None:
toolkit_manager = self._toolkit_manager_class(
team=self._team, user=self._user, context_manager=self.context_manager
)
available_tools = await toolkit_manager.get_tools(state, config)
# Filter to only MaxTool instances (dicts are server-side tools like web_search handled by Anthropic)
return next(
(tool for tool in available_tools if isinstance(tool, MaxTool) and tool.get_name() == tool_name), None
)
async def _invoke_tool(
self, tool: MaxTool, tool_call: AssistantToolCall, config: RunnableConfig
) -> LangchainToolMessage:
# tool_call.id is typed as str|None in some LangChain shapes; OTel rejects None
# attribute values with a warning, so include the id only when present.
tool_span_attributes: dict[str, str | int] = {
"posthog_ai.tool_name": tool_call.name,
"posthog_ai.team_id": self._team.id,
}
if tool_call.id is not None:
tool_span_attributes["posthog_ai.tool_call_id"] = tool_call.id
with _tracer.start_as_current_span("posthog_ai.tool.invoke", attributes=tool_span_attributes):
result = await tool.ainvoke(
ToolCall(type="tool_call", name=tool_call.name, args=tool_call.args, id=tool_call.id),
config=config,
)
# Keep the type-mismatch raise inside the span so OTel records the exception
# on the tool.invoke span rather than on its (unrelated) parent.
if not isinstance(result, LangchainToolMessage):
raise ValueError(
f"Tool '{tool_call.name}' returned {type(result).__name__}, expected LangchainToolMessage"
)
return result
async def _capture_tool_executed(self, tool_call: AssistantToolCall, config: RunnableConfig) -> None:
user_distinct_id = self._get_user_distinct_id(config)
if not user_distinct_id:
return
with _tracer.start_as_current_span("posthoganalytics.capture"):
await database_sync_to_async(posthoganalytics.capture)(
distinct_id=user_distinct_id,
event="ai tool executed",
properties={
**self._get_debug_props(config),
"tool_name": tool_call.name,
},
groups=groups(None, self._team),
send_feature_flags=True,
)
def _max_tool_error_state(
self, error: MaxToolError, tool_call: AssistantToolCall, config: RunnableConfig
) -> PartialAssistantState:
logger.exception(
"maxtool_error",
extra={"tool": tool_call.name, "error": str(error), "retry_strategy": error.retry_strategy},
)
user_distinct_id = self._get_user_distinct_id(config)
capture_exception(
error,
distinct_id=user_distinct_id,
properties={
**self._get_debug_props(config),
"tool": tool_call.name,
"retry_strategy": error.retry_strategy,
},
)
if user_distinct_id:
posthoganalytics.capture(
distinct_id=user_distinct_id,
event="max_tool_error",
properties={
**self._get_debug_props(config),
"tool_name": tool_call.name,
"error_type": error.__class__.__name__,
"retry_strategy": error.retry_strategy,
"error_message": str(error),
},
groups=groups(None, self._team),
)
return self._tool_call_state(f"Tool failed: {error.to_summary()}.{error.retry_hint}", tool_call.id)
def _tool_call_state(self, content: str, tool_call_id: str) -> PartialAssistantState:
return PartialAssistantState(
messages=[
AssistantToolCallMessage(
content=content,
id=str(uuid4()),
tool_call_id=tool_call_id,
)
],
)
async def _state_from_tool_result(
self,
result: LangchainToolMessage,
tool_call: AssistantToolCall,
state: AssistantState,
config: RunnableConfig,
) -> PartialAssistantState:
if isinstance(result.artifact, ToolMessagesArtifact):
return PartialAssistantState(
messages=list(result.artifact.messages),
)
tool_message = AssistantToolCallMessage(
content=str(result.content) if result.content else "",
ui_payload={tool_call.name: result.artifact},
id=str(uuid4()),
tool_call_id=tool_call.id,
)
# Extract agent_mode from switch_mode tool result
# The switch_mode tool returns (content, new_mode) where new_mode is stored in artifact
agent_mode: AgentMode | None = None
if tool_call.name == AssistantTool.SWITCH_MODE and result.artifact:
agent_mode = result.artifact
await self._capture_mode_switch(agent_mode, state, config)
return PartialAssistantState(
messages=[tool_message],
agent_mode=agent_mode,
)
async def _capture_mode_switch(self, agent_mode: AgentMode, state: AssistantState, config: RunnableConfig) -> None:
user_distinct_id = self._get_user_distinct_id(config)
if not user_distinct_id:
return
with _tracer.start_as_current_span("posthoganalytics.capture"):
await database_sync_to_async(posthoganalytics.capture)(
distinct_id=user_distinct_id,
event="ai mode executed",
properties={
**self._get_debug_props(config),
"mode": agent_mode,
"previous_mode": state.agent_mode_or_default,
},
groups=groups(None, self._team),
send_feature_flags=True,
)
def router(self, state: AssistantState) -> Literal["root", "end"]:
last_message = state.messages[-1]
if isinstance(last_message, AssistantToolCallMessage):
return "root" # Let the root either proceed or finish, since it now can see the tool call result
return "end"