: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 time
import uuid
import asyncio
from collections.abc import AsyncGenerator, Iterable
from typing import cast
from django.conf import settings
from django.core.exceptions import ValidationError
from django.db.models import Q
from django.utils import timezone
import pydantic
import structlog
from asgiref.sync import async_to_sync as asgi_async_to_sync
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
from loginas.utils import is_impersonated_session
from prometheus_client import Histogram
from rest_framework import exceptions, serializers, status
from rest_framework.decorators import action
from rest_framework.exceptions import Throttled
from rest_framework.mixins import DestroyModelMixin, ListModelMixin, RetrieveModelMixin
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.viewsets import GenericViewSet
from posthog.schema import AgentMode, AssistantMessage, HumanMessage, MaxBillingContext
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.streaming import sse_streaming_response
from posthog.event_usage import report_user_action
from posthog.exceptions import Conflict, QuotaLimitExceeded
from posthog.exceptions_capture import capture_exception
from posthog.models.user import User
from posthog.rate_limit import (
AIBurstRateThrottle,
AIResearchBurstRateThrottle,
AIResearchSustainedRateThrottle,
AISustainedRateThrottle,
is_team_exempt_from_ai_rate_limit,
)
from posthog.temporal.ai.chat_agent import (
CHAT_AGENT_STREAM_MAX_LENGTH,
CHAT_AGENT_WORKFLOW_TIMEOUT,
ChatAgentWorkflow,
ChatAgentWorkflowInputs,
)
from posthog.temporal.ai.research_agent import (
RESEARCH_AGENT_STREAM_MAX_LENGTH,
RESEARCH_AGENT_WORKFLOW_TIMEOUT,
ResearchAgentWorkflow,
ResearchAgentWorkflowInputs,
)
from products.posthog_ai.backend.context_wrapper import ALLOWED_TYPES as ALLOWED_ATTACHED_CONTEXT_TYPES
from products.posthog_ai.backend.message_routing import SandboxSession
from products.posthog_ai.backend.models.assistant import Conversation
from products.tasks.backend.facade import api as tasks_facade
from products.tasks.backend.facade.access import get_posthog_ai_access_decision
from products.tasks.backend.facade.contracts import TaskDetailDTO
from products.tasks.backend.facade.run_config import INITIAL_PERMISSION_MODE_CHOICES
from ee.billing.quota_limiting import QuotaLimitingCaches, QuotaResource, is_team_limited
from ee.hogai.api.serializers import ConversationMinimalSerializer, ConversationSerializer
from ee.hogai.chat_agent import AssistantGraph
from ee.hogai.core.executor import AgentExecutor
from ee.hogai.queue import ConversationQueueMessage, ConversationQueueStore, QueueFullError, build_queue_message
from ee.hogai.stream.redis_stream import get_conversation_stream_key
from ee.hogai.utils.aio import async_to_sync
from ee.hogai.utils.sse import AssistantSSESerializer
from ee.hogai.utils.types import PartialAssistantState
logger = structlog.get_logger(__name__)
RESEARCH_RATE_LIMIT_MESSAGE = (
"You've reached the usage limit for Research mode, which is currently in beta "
"with limited capacity. Please try again {retry_after}, or switch to a regular "
"conversation for continued access."
)
# Roughly 10k tokens. Every path that accepts a user message shares this, so the limit can't drift
# between them. The frontend mirrors it in `MAX_MESSAGE_LENGTH` (frontend/src/scenes/max/max-constants.tsx).
MAX_MESSAGE_CONTENT_LENGTH = 40000
STREAM_ITERATION_LATENCY_HISTOGRAM = Histogram(
"posthog_ai_stream_iteration_latency_seconds",
"Time between iterations in the async stream loop",
buckets=[0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, float("inf")],
)
class MessageMinimalSerializer(serializers.Serializer):
"""Serializer for appending a message to an existing conversation without triggering AI processing."""
content = serializers.CharField(required=True, max_length=10000)
def _strip_large_spend_history(billing_context: MaxBillingContext, threshold: int = 20) -> MaxBillingContext:
"""Large spend histories can exceed Temporal's 2MB payload limit."""
if billing_context.spend_history and len(billing_context.spend_history) > threshold:
billing_context.spend_history = None
return billing_context
class MessageSerializer(MessageMinimalSerializer):
content = serializers.CharField(
required=True,
allow_null=True, # Null content means we're resuming streaming or continuing previous generation
max_length=MAX_MESSAGE_CONTENT_LENGTH,
)
conversation = serializers.UUIDField(
required=True
) # this either retrieves an existing conversation or creates a new one
contextual_tools = serializers.DictField(required=False, child=serializers.JSONField())
ui_context = serializers.JSONField(required=False)
billing_context = serializers.JSONField(required=False)
trace_id = serializers.UUIDField(required=True)
session_id = serializers.CharField(required=False)
agent_mode = serializers.ChoiceField(required=False, choices=[mode.value for mode in AgentMode])
is_sandbox = serializers.BooleanField(required=False, default=False)
resume_payload = serializers.JSONField(required=False, allow_null=True)
def validate(self, attrs):
data = attrs
if isinstance(data.get("ui_context"), dict):
data["ui_context"].pop("voice_mode", None)
if data["content"] is not None:
try:
message = HumanMessage.model_validate(
{
"content": data["content"],
"ui_context": data.get("ui_context"),
"trace_id": str(data["trace_id"]) if data.get("trace_id") else None,
}
)
except pydantic.ValidationError:
if settings.DEBUG:
raise
raise serializers.ValidationError("Invalid message content.")
data["message"] = message
else:
# NOTE: If content is empty, it means we're resuming streaming or continuing generation with only the contextual_tools potentially different
# Because we intentionally don't add a HumanMessage, we are NOT updating ui_context here
data["message"] = None
billing_context = data.get("billing_context")
if billing_context:
try:
billing_context = _strip_large_spend_history(MaxBillingContext.model_validate(billing_context))
data["billing_context"] = billing_context
except pydantic.ValidationError as e:
capture_exception(e)
# billing data relies on a lot of legacy code, this might break and we don't want to block the conversation
data["billing_context"] = None
if agent_mode := data.get("agent_mode"):
try:
data["agent_mode"] = AgentMode(agent_mode)
except ValueError:
raise serializers.ValidationError("Invalid agent mode.")
return data
class QueueMessageSerializer(serializers.Serializer):
content = serializers.CharField(required=True, allow_blank=False, max_length=MAX_MESSAGE_CONTENT_LENGTH)
contextual_tools = serializers.DictField(required=False, child=serializers.JSONField())
ui_context = serializers.JSONField(required=False)
billing_context = serializers.JSONField(required=False)
agent_mode = serializers.ChoiceField(required=False, choices=[mode.value for mode in AgentMode])
def validate(self, attrs):
data = attrs
if isinstance(data.get("ui_context"), dict):
data["ui_context"].pop("voice_mode", None)
try:
HumanMessage.model_validate(
{
"content": data["content"],
"ui_context": data.get("ui_context"),
}
)
except pydantic.ValidationError:
raise serializers.ValidationError("Invalid message content.")
billing_context = data.get("billing_context")
if billing_context:
try:
parsed_context = _strip_large_spend_history(MaxBillingContext.model_validate(billing_context))
data["billing_context"] = parsed_context.model_dump()
except pydantic.ValidationError as e:
capture_exception(e)
data["billing_context"] = None
if agent_mode := data.get("agent_mode"):
try:
data["agent_mode"] = AgentMode(agent_mode).value
except ValueError:
raise serializers.ValidationError("Invalid agent mode.")
return data
class QueueMessageUpdateSerializer(serializers.Serializer):
content = serializers.CharField(required=True, allow_blank=False, max_length=MAX_MESSAGE_CONTENT_LENGTH)
class SandboxAttachedContextItemSerializer(serializers.Serializer):
"""One typed attachment carried by a sandbox message.
DEPRECATED PATH — do not extend. This structured `attached_context` (and its server-side wrap in
`context_wrapper.py`) exists only for the legacy Max conversations bridge and is removed with it;
the live path wraps context client-side (`products/posthog_ai/frontend/utils/posthogContextBlock.ts`).
"""
type = serializers.ChoiceField(
choices=sorted(ALLOWED_ATTACHED_CONTEXT_TYPES),
help_text=(
"Attachment kind. Entity types carry `id` (+ optional `name`); `text` and `instructions` carry `value`. "
"`instructions` is the caller's own guidance and renders into the trusted context block; every other "
"kind renders into the untrusted block, which tells the agent to read it as data."
),
)
id = serializers.JSONField(
required=False,
help_text="Entity identifier — integer for `dashboard`/`action`, string short_id/UUID otherwise. Absent for `text`.",
)
name = serializers.CharField(
required=False, help_text="Optional human-readable label rendered in the context block."
)
value = serializers.CharField(
required=False, help_text="Free-text content. Only for `text` and `instructions` attachments."
)
def _validate_sandbox_task(task_id: uuid.UUID, team_id: int, user_id: int | None) -> None:
runtime = tasks_facade.task_runtime(task_id, team_id, user_id)
if runtime is None:
raise serializers.ValidationError("Task not found or not accessible.")
if runtime == tasks_facade.TaskRuntime.PI:
raise serializers.ValidationError("Pi tasks cannot be opened in PostHog AI.")
class SandboxOpenSerializer(serializers.Serializer):
"""Request body for `POST /conversations/{id}/open/`. A string `content` processes a turn; a
null/absent `content` warms a sandbox that idles awaiting the first message."""
content = serializers.CharField(
required=False,
allow_null=True,
allow_blank=True,
max_length=MAX_MESSAGE_CONTENT_LENGTH,
help_text="The user's message text. Omit or null to warm a sandbox (boot + idle) ahead of the first message.",
)
trace_id = serializers.UUIDField(
required=False, help_text="Client-generated trace id correlated with the resulting Run's SSE stream."
)
# Deprecated with the legacy Max bridge (see SandboxAttachedContextItemSerializer) — do not extend.
attached_context = serializers.ListField(
required=False,
child=SandboxAttachedContextItemSerializer(),
help_text="Typed PostHog entities (and free text) attached to this message.",
)
initial_permission_mode = serializers.ChoiceField(
choices=INITIAL_PERMISSION_MODE_CHOICES,
required=False,
help_text=(
"Initial permission mode for the sandbox agent session. "
"Defaults to `auto`, which allows safe tool use while preserving explicit confirmations."
),
)
task_id = serializers.UUIDField(
required=False,
help_text=(
"Bind a brand-new sandbox conversation to an existing Task so the first message resumes "
"that Task's run. Honored only when this request creates the conversation row; ignored "
"for an already-existing conversation."
),
)
def validate_task_id(self, value: uuid.UUID) -> uuid.UUID:
"""Resolve the Task to bind, scoped to the team and the requesting user's visibility.
Mirrors the tasks API's `task_visibility_q` gate so a team member can't bind a conversation
to a teammate's private task by guessing its id. Returns the validated id (consumed directly
by the view), so an unreadable id surfaces as a 400 here rather than failing deeper in routing.
"""
team = self.context["team"]
user = self.context["user"]
_validate_sandbox_task(value, team.id, user.id)
return value
class SandboxMessageResponseSerializer(serializers.Serializer):
"""Response for `POST /conversations/{id}/open/` — the IDs the frontend opens SSE against."""
task_id = serializers.CharField(help_text="The products/tasks Task backing the conversation.")
run_id = serializers.CharField(help_text="The Run the frontend opens SSE against.")
trace_id = serializers.CharField(allow_null=True, help_text="Echo of the request trace id, if provided.")
run_status = serializers.CharField(help_text="Current status of the targeted Run (e.g. `queued`, `in_progress`).")
just_created_run = serializers.BooleanField(
help_text="True when a new Run was created (first message, terminal resume, or fresh warm); false for an in-progress follow-up or a reused warm Run."
)
@extend_schema(tags=["max"], extensions={"x-product": "posthog_ai"})
class ConversationViewSet(
TeamAndOrgViewSetMixin, ListModelMixin, RetrieveModelMixin, DestroyModelMixin, GenericViewSet
):
scope_object = "conversation"
scope_object_write_actions = ["create", "update", "partial_update", "patch", "destroy", "cancel"]
serializer_class = ConversationSerializer
queryset = Conversation.objects.all()
lookup_url_kwarg = "conversation"
def _queue_conversation_id(self) -> str:
if not self.lookup_url_kwarg:
raise exceptions.ValidationError("Conversation not provided")
conversation_id = self.kwargs.get(self.lookup_url_kwarg)
if not conversation_id:
raise exceptions.ValidationError("Conversation not provided")
return str(conversation_id)
def _ensure_queue_access(self, request: Request, conversation_id: str) -> Response | None:
try:
# nosemgrep: idor-lookup-without-team (instance scoped to team via get_queryset)
conversation = Conversation.objects.exclude(deleted=True).get(id=conversation_id)
except Conversation.DoesNotExist:
return Response({"error": "Conversation not found"}, status=status.HTTP_404_NOT_FOUND)
if conversation.user != request.user or conversation.team != self.team:
return Response({"error": "Cannot access other users' conversations"}, status=status.HTTP_403_FORBIDDEN)
return None
def _queue_response(self, queue_store: ConversationQueueStore, queue: list[ConversationQueueMessage]) -> Response:
return Response({"messages": queue, "max_queue_messages": queue_store.max_messages})
def safely_get_queryset(self, queryset):
queryset = queryset.select_related("user").exclude(deleted=True)
# Only single retrieval of a specific conversation is allowed for other users' conversations (if ID known)
if self.action != "retrieve":
queryset = queryset.filter(user=self.request.user)
else:
# A LangGraph conversation stays readable by link even once the mirror has linked a task
# to it: the task is a copy, not the source, and must not narrow who can read the chat.
queryset = queryset.filter(
Q(task_id__isnull=True)
| Q(agent_runtime=Conversation.AgentRuntime.LANGGRAPH)
| (
Q(task__team_id=self.team_id, task__deleted=False)
& tasks_facade.visible_tasks_q(self.request.user.id, relation="task")
)
)
# For listing or single retrieval, conversations must be from the assistant and have a title
if self.action in ("list", "retrieve"):
queryset = queryset.filter(
title__isnull=False,
type__in=[Conversation.Type.DEEP_RESEARCH, Conversation.Type.ASSISTANT, Conversation.Type.SLACK],
)
# Hide internal conversations from customers, but show them to support agents during impersonation
if not is_impersonated_session(self.request):
queryset = queryset.filter(is_internal=False)
# `id` breaks ties, because equal `updated_at` values give no stable page order
queryset = queryset.order_by("-updated_at", "-id")
if self.action == "list":
queryset = queryset.defer("approval_decisions", "messages_json", "sandbox_task_id", "sandbox_run_id")
return queryset
def get_throttles(self):
# For message-sending / warming actions, throttling is handled in check_throttles() for conditional logic
if self.action in ("create", "open"):
return []
return super().get_throttles()
def _is_research_request(self, request: Request) -> bool:
"""Check if the request is for a research conversation."""
# Check if it's a new conversation with research mode
agent_mode = request.data.get("agent_mode")
if agent_mode == AgentMode.RESEARCH or agent_mode == AgentMode.RESEARCH.value:
return True
# Check if it's an existing deep research conversation
conversation_id = request.data.get("conversation")
if conversation_id:
try:
conversation = Conversation.objects.exclude(deleted=True).get(id=conversation_id, team=self.team)
if conversation.type == Conversation.Type.DEEP_RESEARCH:
return True
except (Conversation.DoesNotExist, ValidationError):
# DoesNotExist or ValidationError (invalid UUID) - not a research conversation
pass
return False
def check_throttles(self, request: Request):
# Apply the AI throttles to the message-sending / warming actions — `open` provisions a real
# sandbox Run whether or not it carries a message, so it shares the same rate limit as `create`.
if self.action not in ("create", "open"):
return super().check_throttles(request)
# Skip throttling in local development
if settings.DEBUG:
return
# Determine which throttles to apply based on request type
is_research = self._is_research_request(request)
if is_research:
if is_team_exempt_from_ai_rate_limit(self.team_id):
return
throttles = [AIResearchBurstRateThrottle(), AIResearchSustainedRateThrottle()]
else:
# Skip throttling for paying customers
if self.organization.customer_id:
return
throttles = [AIBurstRateThrottle(), AISustainedRateThrottle()]
for throttle in throttles:
if not throttle.allow_request(request, self):
wait = throttle.wait()
if wait is not None:
if wait < 60:
retry_after = f"in {int(wait)} seconds"
elif wait < 3600:
retry_after = f"in {int(wait / 60)} minutes"
else:
retry_after = "later today"
else:
retry_after = "later"
if is_research:
detail = RESEARCH_RATE_LIMIT_MESSAGE.format(retry_after=retry_after)
else:
detail = f"You've reached PostHog AI's usage limit for the moment. Please try again {retry_after}."
raise Throttled(wait=wait, detail=detail)
def get_serializer_class(self):
if self.action == "create":
return MessageSerializer
if self.action == "append_message":
return MessageMinimalSerializer
if self.action == "list":
return ConversationMinimalSerializer
return super().get_serializer_class()
def get_serializer(self, *args, **kwargs):
if self.action in ("list", "retrieve") and args:
context = kwargs.pop("context", self.get_serializer_context())
context["conversation_task_dtos_by_id"] = self._conversation_task_dtos_by_id(args[0])
kwargs["context"] = context
return super().get_serializer(*args, **kwargs)
def _conversation_task_dtos_by_id(self, instance) -> dict[str, TaskDetailDTO]:
conversations = (
[instance] if isinstance(instance, Conversation) else list(cast(Iterable[Conversation], instance))
)
task_ids = list({conversation.task_id for conversation in conversations if conversation.task_id is not None})
return {
str(task_id): task
for task_id, task in tasks_facade.get_conversation_task_dtos(
task_ids, self.team_id, cast(User, self.request.user).id
).items()
}
def get_serializer_context(self):
context = super().get_serializer_context()
# drf-spectacular introspects with a fake view (no URL kwargs), so `self.team` would
# raise KeyError: 'team_id'. Skip the eager team/user lookup during schema generation.
if getattr(self, "swagger_fake_view", False):
return context
context["team"] = self.team
context["user"] = cast(User, self.request.user)
return context
def create(self, request: Request, *args, **kwargs):
"""
Unified endpoint that handles both conversation creation and streaming.
- If message is provided: Start new conversation processing
- If no message: Stream from existing conversation
"""
if is_team_limited(self.team.api_token, QuotaResource.AI_CREDITS, QuotaLimitingCaches.QUOTA_LIMITER_CACHE_KEY):
raise QuotaLimitExceeded(
"Your organization reached its AI credit usage limit. Increase the limits in Billing settings, or ask an org admin to do so."
)
serializer = self.get_serializer(data=request.data)
serializer.is_valid(raise_exception=True)
conversation_id = serializer.validated_data["conversation"]
has_message = serializer.validated_data.get("content") is not None
is_research = serializer.validated_data.get("agent_mode") == AgentMode.RESEARCH
is_new_conversation = False
# Safely set the lookup kwarg for potential error handling
if self.lookup_url_kwarg:
self.kwargs[self.lookup_url_kwarg] = conversation_id
try:
# nosemgrep: idor-lookup-without-team, idor-taint-user-input-to-model-get (user+team check immediately after)
conversation = Conversation.objects.get(id=conversation_id)
if conversation.user != request.user or conversation.team != self.team:
return Response(
{"error": "Cannot access other users' conversations"}, status=status.HTTP_400_BAD_REQUEST
)
if conversation.deleted:
return Response({"error": "Conversation does not exist"}, status=status.HTTP_404_NOT_FOUND)
except Conversation.DoesNotExist:
# Conversation doesn't exist, create it if we have a message
if not has_message:
return Response(
{"error": "Cannot stream from non-existent conversation"}, status=status.HTTP_400_BAD_REQUEST
)
# Use frontend-provided conversation ID
# Mark conversation as internal if created during an impersonated session (support agents)
is_impersonated = is_impersonated_session(request)
conversation_type = Conversation.Type.DEEP_RESEARCH if is_research else Conversation.Type.ASSISTANT
# This endpoint is LangGraph-only — sandbox conversations are created via `open`. New rows
# are always LangGraph (the model default), never stamped from the sandbox flag here.
conversation = Conversation.objects.create(
user=cast(User, request.user),
team=self.team,
id=conversation_id,
type=conversation_type,
is_internal=is_impersonated,
agent_runtime=Conversation.AgentRuntime.LANGGRAPH,
)
is_new_conversation = True
is_idle = conversation.status == Conversation.Status.IDLE
has_message = serializer.validated_data.get("message") is not None
has_resume_payload = serializer.validated_data.get("resume_payload") is not None
# Sandbox conversations — including the legacy LangGraph→sandbox conversion of a reopened
# thread — are served exclusively by the `open` endpoint. Reject any that reach this one,
# whether an already-sandbox row or a sandbox-signalling body, so a sandbox conversation can
# never fall through to the LangGraph workflow below.
if (
conversation.agent_runtime == Conversation.AgentRuntime.SANDBOX
or serializer.validated_data.get("is_sandbox", False)
or serializer.validated_data.get("agent_mode") == AgentMode.SANDBOX
):
raise exceptions.ValidationError("Sandbox conversations must be opened via the open endpoint.")
if conversation.type == Conversation.Type.DEEP_RESEARCH:
if not is_new_conversation and is_idle and has_message and not has_resume_payload:
conversation.type = Conversation.Type.ASSISTANT
conversation.save(update_fields=["type", "updated_at"])
is_research = False
else:
is_research = True
if has_message and not is_idle:
raise Conflict("Cannot resume streaming with a new message")
# If the frontend is trying to resume streaming for a finished conversation, return a conflict error
if not has_message and conversation.status == Conversation.Status.IDLE and not has_resume_payload:
raise exceptions.ValidationError("Cannot continue streaming from an idle conversation")
is_impersonated = is_impersonated_session(request)
workflow_inputs: ChatAgentWorkflowInputs | ResearchAgentWorkflowInputs
workflow_class: type[ChatAgentWorkflow] | type[ResearchAgentWorkflow]
if is_research:
workflow_inputs = ResearchAgentWorkflowInputs(
team_id=self.team_id,
user_id=cast(User, request.user).pk, # Use pk instead of id for User model
conversation_id=conversation.id,
stream_key=get_conversation_stream_key(conversation.id),
message=serializer.validated_data["message"].model_dump() if has_message else None,
is_new_conversation=is_new_conversation,
trace_id=serializer.validated_data["trace_id"],
session_id=request.headers.get("X-POSTHOG-SESSION-ID"), # Relies on posthog-js __add_tracing_headers
billing_context=serializer.validated_data.get("billing_context"),
is_agent_billable=False,
is_impersonated=is_impersonated,
resume_payload=serializer.validated_data.get("resume_payload"),
)
workflow_class = ResearchAgentWorkflow
timeout = RESEARCH_AGENT_WORKFLOW_TIMEOUT
max_length = RESEARCH_AGENT_STREAM_MAX_LENGTH
else:
is_agent_billable = not is_impersonated
workflow_inputs = ChatAgentWorkflowInputs(
team_id=self.team_id,
user_id=cast(User, request.user).pk, # Use pk instead of id for User model
conversation_id=conversation.id,
stream_key=get_conversation_stream_key(conversation.id),
message=serializer.validated_data["message"].model_dump() if has_message else None,
contextual_tools=serializer.validated_data.get("contextual_tools"),
is_new_conversation=is_new_conversation,
trace_id=serializer.validated_data["trace_id"],
session_id=request.headers.get("X-POSTHOG-SESSION-ID"), # Relies on posthog-js __add_tracing_headers
billing_context=serializer.validated_data.get("billing_context"),
agent_mode=serializer.validated_data.get("agent_mode"),
use_checkpointer=True,
is_agent_billable=is_agent_billable,
is_impersonated=is_impersonated,
resume_payload=serializer.validated_data.get("resume_payload"),
)
workflow_class = ChatAgentWorkflow
timeout = CHAT_AGENT_WORKFLOW_TIMEOUT
max_length = CHAT_AGENT_STREAM_MAX_LENGTH
async def async_stream(
workflow_inputs: ChatAgentWorkflowInputs | ResearchAgentWorkflowInputs,
) -> AsyncGenerator[bytes]:
SSE_KEEPALIVE_COMMENT = b": keepalive\n\n"
SSE_KEEPALIVE_INTERVAL = 15 # seconds — well under typical LB idle timeouts (60s)
serializer = AssistantSSESerializer()
stream_manager = AgentExecutor(conversation, timeout=timeout, max_length=max_length)
last_yield_time = time.time()
last_chunk_time = last_yield_time
aiter = stream_manager.astream(workflow_class, workflow_inputs).__aiter__()
while True:
next_task = asyncio.ensure_future(aiter.__anext__())
try:
while not next_task.done():
elapsed = time.time() - last_yield_time
wait_time = max(0.1, SSE_KEEPALIVE_INTERVAL - elapsed)
done, _ = await asyncio.wait({next_task}, timeout=wait_time)
if not done:
yield SSE_KEEPALIVE_COMMENT
last_yield_time = time.time()
except BaseException:
if not next_task.done():
next_task.cancel()
raise
try:
chunk = next_task.result()
except StopAsyncIteration:
break
now = time.time()
STREAM_ITERATION_LATENCY_HISTOGRAM.observe(now - last_chunk_time)
last_chunk_time = now
last_yield_time = now
event = await serializer.dumps(chunk)
yield event.encode("utf-8")
return sse_streaming_response(
async_stream(workflow_inputs)
if settings.SERVER_GATEWAY_INTERFACE == "ASGI"
else async_to_sync(lambda: async_stream(workflow_inputs)),
endpoint="max_conversation",
)
@action(detail=True, methods=["GET", "POST"], url_path="queue")
def queue(self, request: Request, *args, **kwargs):
conversation_id = self._queue_conversation_id()
error_response = self._ensure_queue_access(request, conversation_id)
if error_response:
return error_response
queue_store = ConversationQueueStore(conversation_id)
if request.method == "GET":
return self._queue_response(queue_store, queue_store.list())
serializer = QueueMessageSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
message = build_queue_message(
content=serializer.validated_data["content"],
contextual_tools=serializer.validated_data.get("contextual_tools"),
ui_context=serializer.validated_data.get("ui_context"),
billing_context=serializer.validated_data.get("billing_context"),
agent_mode=serializer.validated_data.get("agent_mode"),
session_id=request.headers.get("X-POSTHOG-SESSION-ID"),
)
try:
queue = queue_store.enqueue(message)
except QueueFullError:
return Response(
{
"error": "queue_full",
"detail": "Only two messages can be queued at a time.",
},
status=status.HTTP_409_CONFLICT,
)
return self._queue_response(queue_store, queue)
@extend_schema(parameters=[OpenApiParameter("queue_id", OpenApiTypes.STR, OpenApiParameter.PATH)])
@action(detail=True, methods=["PATCH", "DELETE"], url_path=r"queue/(?P<queue_id>[^/.]+)")
def queue_item(self, request: Request, queue_id: str, *args, **kwargs):
conversation_id = self._queue_conversation_id()
error_response = self._ensure_queue_access(request, conversation_id)
if error_response:
return error_response
queue_store = ConversationQueueStore(conversation_id)
queue = queue_store.list()
queue_index = next((index for index, item in enumerate(queue) if item.get("id") == queue_id), None)
if queue_index is None:
return Response({"detail": "Queue message not found."}, status=status.HTTP_404_NOT_FOUND)
if request.method == "PATCH":
serializer = QueueMessageUpdateSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
queue = queue_store.update(queue_id, serializer.validated_data["content"])
else:
queue = queue_store.delete(queue_id)
return self._queue_response(queue_store, queue)
@action(detail=True, methods=["POST"], url_path="queue/clear")
def clear_queue(self, request: Request, *args, **kwargs):
conversation_id = self._queue_conversation_id()
error_response = self._ensure_queue_access(request, conversation_id)
if error_response:
return error_response
queue_store = ConversationQueueStore(conversation_id)
return self._queue_response(queue_store, queue_store.clear())
@extend_schema(
request=SandboxOpenSerializer,
responses={
200: SandboxMessageResponseSerializer,
204: OpenApiResponse(description="Warm request that provisioned nothing (pool full / released)."),
400: OpenApiResponse(description="Conversation or task uses an unsupported runtime."),
},
description=(
"Create-or-resume a sandbox conversation — the single sandbox session opener. With `content`, "
"processes the turn (first message, in-progress follow-up, or terminal resume); without `content`, "
"warms a sandbox that idles awaiting the first message. Returns the `(task, run)` handle the "
"frontend opens SSE against. The conversation row is created on first use from the URL id."
),
)
@action(detail=True, methods=["POST"], url_path="open")
def open(self, request: Request, *args, **kwargs):
# Both warming and messaging launch a Run, so gate both on the AI-credit quota.
if is_team_limited(self.team.api_token, QuotaResource.AI_CREDITS, QuotaLimitingCaches.QUOTA_LIMITER_CACHE_KEY):
raise QuotaLimitExceeded(
"Your organization reached its AI credit usage limit. Increase the limits in Billing settings, or ask an org admin to do so."
)
# Checked before the lookup, so a denied caller cannot continue an existing sandbox conversation either.
if not get_posthog_ai_access_decision(cast(User, request.user), self.team.organization).allowed:
raise exceptions.ValidationError("This conversation is not on the sandbox runtime.")
serializer = SandboxOpenSerializer(data=request.data, context=self.get_serializer_context())
serializer.is_valid(raise_exception=True)
conversation, created = self._get_or_create_sandbox_conversation(
request, bind_task=serializer.validated_data.get("task_id")
)
if conversation.task_id is not None:
_validate_sandbox_task(conversation.task_id, self.team.id, request.user.id)
if conversation.agent_runtime != Conversation.AgentRuntime.SANDBOX:
raise exceptions.ValidationError("This conversation is not on the sandbox runtime.")
has_content = bool(serializer.validated_data.get("content"))
if has_content and conversation.title is None:
conversation.title = serializer.validated_data["content"][:80]
conversation.save(update_fields=["title"])
return self._route_sandbox_message(request, conversation, created=created)
def _get_or_create_sandbox_conversation(
self, request: Request, *, bind_task: uuid.UUID | None = None
) -> tuple[Conversation, bool]:
"""Resolve the URL-keyed conversation, creating it on first use (the client mints the id).
`open` is create-or-resume: a brand-new conversation (first warm or first message) has no row
yet, so a plain `get_object()` would 404. A brand-new row is only born on the sandbox runtime,
and `open` checks PostHog AI 2.0 access first, so a caller outside it can't spam orphaned rows by
POSTing random ids. Returns whether the row was created this request so the caller can
drop it again if nothing ends up being provisioned.
`bind_task` (already validated for team + visibility by `SandboxOpenSerializer`) binds the new
row to an existing Task, so the first message resumes that Task's run instead of starting a
fresh task. It only applies on create — an existing conversation keeps the Task it was born with.
"""
conversation_id = self.kwargs[self.lookup_url_kwarg]
user = cast(User, request.user)
try:
# nosemgrep: idor-lookup-without-team, idor-taint-user-input-to-model-get (user+team checked below)
conversation = Conversation.objects.get(id=conversation_id)
except Conversation.DoesNotExist:
conversation = Conversation.objects.create(
user=user,
team=self.team,
id=conversation_id,
type=Conversation.Type.ASSISTANT,
is_internal=is_impersonated_session(request),
agent_runtime=Conversation.AgentRuntime.SANDBOX,
task_id=bind_task,
)
return conversation, True
if conversation.user != user or conversation.team != self.team:
raise exceptions.PermissionDenied("Cannot access other users' conversations")
if conversation.deleted:
raise exceptions.NotFound("Conversation does not exist")
return conversation, False
def _auto_route_repository(self, request: Request, conversation: Conversation, user: User) -> str | None:
"""Auto-select the repository a sandbox conversation's first message is about.
Runs only on a first message — no backing Task yet (`task_id is None`) and real content.
Followups and resumes reuse the existing Task's repository, and warming has no message to
route on, so neither triggers the explicit repository mention match. Selection never raises;
any failure degrades to None — a repo-less sandbox — so it can't block the conversation.
"""
if conversation.task_id is not None:
return None
content = request.data.get("content")
if not isinstance(content, str) or not content.strip():
return None
return asgi_async_to_sync(tasks_facade.select_repository_for_message)(
self.team_id, user.pk, content, origin_product=tasks_facade.TaskOriginProduct.POSTHOG_AI
)
def _route_sandbox_message(
self,
request: Request,
conversation: Conversation,
*,
created: bool = False,
) -> Response:
user = cast(User, request.user)
repository = self._auto_route_repository(request, conversation, user)
result = SandboxSession(conversation, user).open(request.data, repository=repository)
if result is None:
# Warm intent that provisioned nothing (pool full / released) — no run to open. Drop the
# row if we created it this request so a content-less warm can't leave orphaned conversations.
if created:
conversation.delete()
return Response(status=status.HTTP_204_NO_CONTENT)
content = request.data.get("content")
if isinstance(content, str) and content.strip():
report_user_action(
user,
"prompt sent",
{
"trace_id": result.trace_id,
"conversation_id": str(conversation.id),
"execution_type": "sandbox",
"agent_runtime": "sandbox",
"just_created_run": result.just_created_run,
"has_attached_context": result.attached_context_count > 0,
"attached_context_count": result.attached_context_count,
},
team=self.team,
request=request,
)
# attached_context_count is internal telemetry plumbing — keep it out of the response body.
return Response(result.model_dump(exclude={"attached_context_count"}), status=status.HTTP_200_OK)
@extend_schema(
description="Cancel the conversation's in-progress LangGraph run.",
responses={
204: OpenApiResponse(description="Cancellation accepted, or already cancelling."),
422: OpenApiResponse(description="Failed to cancel the conversation."),
},
)
@action(detail=True, methods=["PATCH"])
def cancel(self, request: Request, *args, **kwargs):
# Sandbox runs cancel through the generic tasks relay (`runs/{run}/command/`); this endpoint
# serves the LangGraph runtime only.
conversation = self.get_object()
# IDLE is intentionally not short-circuited: during the handoff between the main
# workflow completing and a queued workflow starting, the status is briefly IDLE
# even though a queued Temporal workflow may be running.
if conversation.status == Conversation.Status.CANCELING:
return Response(status=status.HTTP_204_NO_CONTENT)
async def cancel_workflow():
agent_executor = AgentExecutor(conversation)
await agent_executor.cancel_workflow()
try:
asgi_async_to_sync(cancel_workflow)()
except Exception as e:
logger.exception("Failed to cancel conversation", conversation_id=conversation.id, error=str(e))
return Response({"error": "Failed to cancel conversation"}, status=status.HTTP_422_UNPROCESSABLE_ENTITY)
return Response(status=status.HTTP_204_NO_CONTENT)
@extend_schema(
description="Delete a conversation.",
responses={204: None},
)
def destroy(self, request: Request, *args, **kwargs) -> Response:
instance: Conversation = self.get_object()
Conversation.objects.filter(pk=instance.pk).update(deleted=True, deleted_at=timezone.now())
if instance.task_id is not None:
# The task is the chat's other representation; a deleted chat must not stay readable there.
tasks_facade.soft_delete_task(instance.task_id, self.team_id, cast(User, request.user).id)
return Response(status=status.HTTP_204_NO_CONTENT)
@action(detail=True, methods=["POST"], url_path="append_message")
def append_message(self, request: Request, *args, **kwargs):
"""
Appends a message to an existing conversation without triggering AI processing.
This is used for client-side generated messages that need to be persisted
(e.g., support ticket confirmation messages).
"""
conversation = self.get_object()
serializer = self.get_serializer(data=request.data)
serializer.is_valid(raise_exception=True)
content = serializer.validated_data["content"]
message = AssistantMessage(content=content, id=str(uuid.uuid4()))
async def append_to_state():
user = cast(User, request.user)
graph = AssistantGraph(self.team, user).compile_full_graph()
# Empty checkpoint_ns targets the root graph (not subgraphs)
config = {"configurable": {"thread_id": str(conversation.id), "checkpoint_ns": ""}}
await graph.aupdate_state(
config,
PartialAssistantState(messages=[message]),
)
try:
asgi_async_to_sync(append_to_state)()
except Exception as e:
logger.exception("Failed to append message to conversation", conversation_id=conversation.id, error=str(e))
return Response({"error": "Failed to append message"}, status=status.HTTP_422_UNPROCESSABLE_ENTITY)
return Response({"id": message.id}, status=status.HTTP_201_CREATED)