: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
from textwrap import dedent
from types import SimpleNamespace
from typing import Any
from pydantic import BaseModel, Field
from rest_framework.exceptions import ValidationError
from posthog.schema import FeatureFlagGroupType
from posthog.exceptions_capture import capture_exception
from posthog.scopes import APIScopeObject
from posthog.sync import database_sync_to_async
from products.access_control.backend.facade.user_access_control import AccessControlLevel
from products.feature_flags.backend.facade.api import create_flag
from products.feature_flags.backend.models.evaluation_context import TeamDefaultEvaluationContext
from products.feature_flags.backend.models.feature_flag import FeatureFlag
from ee.hogai.tool import MaxTool
class MultivariateVariant(BaseModel):
"""Schema for a multivariate flag variant."""
key: str = Field(description="Variant key (e.g., 'control', 'test', 'variant_a')")
name: str | None = Field(default=None, description="Optional human-readable variant name")
rollout_percentage: int = Field(ge=0, le=100, description="Percentage of users assigned to this variant (0-100)")
class FeatureFlagCreationSchema(BaseModel):
"""Structured schema for AI-powered feature flag creation using PostHog's native types."""
key: str = Field(
description="Unique flag key in kebab-case (e.g., 'new-dashboard', 'dark-mode'). "
"Must only contain letters, numbers, underscores, and hyphens. Pattern: ^[a-zA-Z0-9_-]+$"
)
name: str = Field(description="Human-readable flag name")
description: str | None = Field(default=None, description="Optional description of what the flag controls")
active: bool = Field(default=True, description="Whether the flag is active")
group_type: str | None = Field(
default=None,
description="Group type name for group-based targeting (e.g., 'organization', 'company')",
)
groups: list[FeatureFlagGroupType] = Field(
default_factory=list,
description="Feature flag groups containing properties and rollout percentage. "
"Uses PostHog's native FeatureFlagGroupType schema.",
)
tags: list[str] = Field(
default_factory=list,
description="Tags for organizing and categorizing the flag. Some projects require at least one "
"tag on every new flag, and reject a create that carries none.",
)
variants: list[MultivariateVariant] | None = Field(
default=None,
description="Multivariate variants for A/B testing. If provided, creates a multivariate flag. "
"Variant rollout percentages should sum to 100. "
"Common example: [{'key': 'control', 'name': 'Control', 'rollout_percentage': 50}, "
"{'key': 'test', 'name': 'Test', 'rollout_percentage': 50}]",
)
evaluation_contexts: list[str] | None = Field(
default=None,
description="Evaluation context names (e.g. 'production', 'staging') that control where this flag "
"evaluates at runtime. Some projects require at least one evaluation context on every new flag. "
"If omitted, the project's default evaluation contexts are applied automatically when configured. "
"An explicit empty list skips the defaults.",
)
FEATURE_FLAG_CREATION_TOOL_DESCRIPTION = dedent("""
Use this tool to create feature flags with optional property-based targeting and multivariate variants.
# When to use
- The user wants to create a new feature flag
- The user wants to roll out a feature to a percentage of users
- The user wants to target specific users by properties (email, country, etc.)
- The user wants a multivariate flag to back an A/B test (to create and run the actual experiment, follow up with the `create_experiment` tool)
# Flag Types
## Simple Boolean Flags
- Roll out to all users (100% rollout)
- Roll out to a percentage of users (e.g., 10% rollout)
## Property-Based Targeting
- Target users by person properties (email, country, etc.)
- Target groups by group properties (plan, employee_count, etc.)
- Combine property filters with rollout percentages
## Multivariate Flags (A/B Tests)
- Create flags with multiple variants (control, test, etc.)
- Specify rollout percentages for each variant (must sum to 100)
- Can be combined with property targeting for segmented experiments
""").strip()
class CreateFeatureFlagToolArgs(BaseModel):
feature_flag: FeatureFlagCreationSchema = Field(
description=dedent("""
The complete feature flag configuration to create.
# Required Fields
- **key**: Unique flag key in kebab-case (e.g., 'new-dashboard', 'dark-mode')
Must only contain letters, numbers, underscores, and hyphens
- **name**: Human-readable flag name (e.g., 'New Dashboard Feature')
# Optional Fields
- **description**: Description of what the flag controls
- **active**: Whether the flag is active (default: true)
- **group_type**: Group type name for group-based targeting (e.g., 'organization')
- **groups**: Array of targeting groups (see Groups Structure below)
- **tags**: Array of tag strings for organizing flags
- **variants**: Array of variants for A/B testing (see Variants Structure below)
- **evaluation_contexts**: Array of evaluation context names (e.g. ['production', 'staging'])
controlling where the flag evaluates at runtime. Some projects require at least one on every
new flag; omit this field entirely to apply the project's configured defaults when set
(an explicit empty list skips the defaults).
# Groups Structure
Each group defines targeting criteria with AND logic within the group:
- **properties**: Array of property filters (empty array [] for no property filtering)
- **rollout_percentage**: Percentage of matching users to target (0-100, or null for 100%)
Property filter structure:
```json
{
"key": "email",
"value": "@company.com",
"operator": "icontains",
"type": "person"
}
```
Operators: "exact", "is_not", "icontains", "not_icontains", "gt", "lt", "gte", "lte", "is_set", "is_not_set"
Types: "person" for user properties, "group" for group properties (requires group_type_index)
# Variants Structure (for A/B tests)
- **key**: Variant identifier (e.g., 'control', 'test')
- **name**: Human-readable variant name (optional)
- **rollout_percentage**: Percentage for this variant (all variants must sum to 100)
# Examples
## Simple 50% Rollout
```json
{
"key": "new-feature",
"name": "New Feature",
"groups": [{"properties": [], "rollout_percentage": 50}]
}
```
## Property-Based Targeting
```json
{
"key": "beta-feature",
"name": "Beta Feature",
"groups": [{
"properties": [{
"key": "email",
"value": "@company.com",
"operator": "icontains",
"type": "person"
}],
"rollout_percentage": null
}]
}
```
## A/B Test with 2 Variants
```json
{
"key": "checkout-test",
"name": "Checkout Flow A/B Test",
"variants": [
{"key": "control", "name": "Current Flow", "rollout_percentage": 50},
{"key": "test", "name": "New Flow", "rollout_percentage": 50}
],
"groups": [{"properties": [], "rollout_percentage": null}]
}
```
## Group-Based Flag (Organizations)
```json
{
"key": "enterprise-feature",
"name": "Enterprise Feature",
"group_type": "organization",
"groups": [{
"properties": [{
"key": "plan",
"value": "enterprise",
"operator": "exact",
"type": "group",
"group_type_index": 0
}],
"rollout_percentage": null
}]
}
```
# Critical Rules
- Keys must match pattern ^[a-zA-Z0-9_-]+$ (no spaces or special characters)
- For A/B tests, variant rollout_percentages MUST sum to 100
- Always include at least one group (even if properties is empty)
- For group-based flags, set group_type and include group_type_index in property filters
""").strip()
)
class CreateFeatureFlagTool(MaxTool):
name: str = "create_feature_flag"
description: str = FEATURE_FLAG_CREATION_TOOL_DESCRIPTION
args_schema: type[BaseModel] = CreateFeatureFlagToolArgs
def get_required_resource_access(
self,
) -> list[tuple[APIScopeObject, AccessControlLevel]]:
"""
Creating a feature flag requires editor-level access to feature flags.
This check runs before the tool executes.
"""
return [("feature_flag", "editor")]
async def _arun_impl(self, feature_flag: FeatureFlagCreationSchema) -> tuple[str, dict[str, Any]]:
"""Create feature flag"""
try:
flag_schema = feature_flag
aggregation_group_type_index = None
group_type_display_name = None
if flag_schema.group_type:
@database_sync_to_async
def get_group_mapping() -> dict | None:
from posthog.models.group_type_mapping import get_group_types_for_project
target = flag_schema.group_type.lower() if flag_schema.group_type else None
for m in get_group_types_for_project(self._team.project_id):
if m["group_type"] == target:
return m
return None
group_mapping = await get_group_mapping()
if not group_mapping:
return (
f"Group type '{flag_schema.group_type}' does not exist for this project",
{"error": "group_type_not_found"},
)
aggregation_group_type_index = group_mapping["group_type_index"]
group_type_display_name = group_mapping["name_plural"] or flag_schema.group_type
filters: dict[str, Any] = {}
if aggregation_group_type_index is not None:
filters["aggregation_group_type_index"] = aggregation_group_type_index
filters["groups"] = [group.model_dump(exclude_none=True) for group in flag_schema.groups]
if flag_schema.variants:
filters["multivariate"] = {
"variants": [variant.model_dump(exclude_none=True) for variant in flag_schema.variants]
}
serializer_data: dict[str, Any] = {
"key": flag_schema.key,
"name": flag_schema.name,
"active": flag_schema.active,
"filters": filters,
"tags": flag_schema.tags,
}
# Unspecified (None) falls back to the project defaults; an explicit empty list is left as-is.
evaluation_contexts = flag_schema.evaluation_contexts
if evaluation_contexts is None:
evaluation_contexts = await self._get_default_evaluation_contexts()
if evaluation_contexts:
serializer_data["evaluation_contexts"] = evaluation_contexts
# Mock request following established patterns
mock_request = SimpleNamespace(
user=self._user,
method="POST",
successful_authenticator=None,
is_posthog_ai=True,
session={},
data=serializer_data,
META={},
headers={},
)
team = self._team
@database_sync_to_async
def create_flag_through_facade() -> FeatureFlag:
return create_flag(serializer_data, team=team, user=self._user, request=mock_request)
flag = await create_flag_through_facade()
flag_url = f"/project/{self._team.project_id}/feature-flags/{flag.id}"
targeting_info = self._format_targeting_info(flag_schema, group_type_display_name)
contexts_info = (
f" with evaluation contexts: {', '.join(evaluation_contexts)}" if evaluation_contexts else ""
)
return (
f"Successfully created feature flag '{flag_schema.name}' (key: {flag_schema.key}){targeting_info}{contexts_info}. View at {flag_url}",
{
"flag_id": flag.id,
"flag_key": flag_schema.key,
"flag_name": flag_schema.name,
"url": flag_url,
"evaluation_contexts": evaluation_contexts,
},
)
except ValidationError as e:
errors = e.detail if hasattr(e, "detail") else str(e)
if isinstance(errors, dict) and "key" in errors:
key_errors = errors["key"]
if any("already" in str(err).lower() for err in key_errors):
@database_sync_to_async
def get_existing_flag() -> FeatureFlag | None:
return FeatureFlag.objects.filter(team=self._team, key=flag_schema.key).first()
existing = await get_existing_flag()
if existing:
flag_url = f"/project/{self._team.project_id}/feature-flags/{existing.id}"
return (
f"A feature flag with key '{flag_schema.key}' already exists. You can view it at {flag_url}",
{"flag_id": existing.id},
)
if isinstance(errors, dict):
error_messages = []
for field, field_errors in errors.items():
for error in field_errors if isinstance(field_errors, list) else [field_errors]:
error_messages.append(f"{field}: {error}")
return (
f"Failed to create feature flag: {'; '.join(error_messages)}",
{"error": "validation_error", "details": errors},
)
return f"Failed to create feature flag: {errors}", {"error": "validation_error"}
except ValueError as e:
return f"Failed to create feature flag: {str(e)}", {"error": str(e)}
except Exception as e:
capture_exception(e, {"team_id": self._team.id, "user_id": self._user.id})
return f"Failed to create feature flag: {str(e)}", {"error": str(e)}
@database_sync_to_async
def _get_default_evaluation_contexts(self) -> list[str]:
"""Return the project's default evaluation context names, if defaults are enabled."""
if not self._team.default_evaluation_contexts_enabled:
return []
return list(
TeamDefaultEvaluationContext.objects.filter(team=self._team)
.select_related("evaluation_context")
.values_list("evaluation_context__name", flat=True)
)
def _format_targeting_info(self, schema: FeatureFlagCreationSchema, group_display_name: str | None) -> str:
"""Format targeting information for success message."""
parts = []
# Add multivariate info first if present
if schema.variants:
variant_count = len(schema.variants)
if variant_count == 2:
parts.append("A/B test with 2 variants")
else:
parts.append(f"multivariate with {variant_count} variants")
# Count total property filters across all groups
total_properties = sum(len(group.properties or []) for group in schema.groups)
if total_properties > 0:
parts.append(f"{total_properties} property filter(s)")
if group_display_name:
parts.append(f"targeting {group_display_name}")
# Check if any group has a rollout percentage
rollout_percentages = [
group.rollout_percentage for group in schema.groups if group.rollout_percentage is not None
]
if rollout_percentages:
# If there's just one group with a percentage, show it
if len(rollout_percentages) == 1:
pct = rollout_percentages[0]
# Format as int if it's a whole number, otherwise as float
pct_str = f"{int(pct)}" if pct == int(pct) else f"{pct}"
parts.append(f"{pct_str}% rollout")
else:
parts.append("multiple rollout rules")
if parts:
return " with " + ", ".join(parts)
return ""