: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 { z } from 'zod'
import type { Schemas } from '@/api/generated'
import { ToolInputValidationError } from '@/lib/errors'
import { normalizeParamAliases } from '@/tools/cast-helpers'
import { withConditionIds } from '@/tools/featureFlags/conditionIds'
import { resolveFlagsByKey } from '@/tools/featureFlags/resolveFlagsByKey'
import { withPostHogUrl, type WithPostHogUrl } from '@/tools/tool-utils'
import type { Context, ToolBase } from '@/tools/types'
import { withVariantScreenshotUrls } from './variantDetails'
/**
* `experiment-get-by-flag-key` fetches an experiment by its feature flag key, the identifier
* agents hold when `experiment-get` wants a numeric ID. The experiments list has no key filter,
* but the flag row carries `experiment_set`, so resolving the key to its flag is enough.
*
* A miss is data, not an error: the dominant caller is an existence check before
* `experiment-create` (same pattern as `feature-flag-get-definition-by-key`). Several
* experiments on one flag is also data, because `experiment-duplicate` reuses the source flag,
* so re-runs stack up; the tool picks the single live one when there is one and otherwise
* returns the candidates. Only an ambiguous flag key still throws.
*/
const schema = z.preprocess(
normalizeParamAliases({ feature_flag_key: ['flagKey', 'flag_key', 'featureFlagKey', 'key'] }),
z.object({
feature_flag_key: z
.string()
.describe('The experiment\'s feature flag key: the string identifier used in code (e.g. "new-checkout").'),
})
)
type Params = z.infer<typeof schema>
interface ExperimentCandidate {
id: number
name: string
status: string | null
archived: boolean
start_date: string | null
end_date: string | null
created_at: string | null
}
interface ExperimentLookupMiss {
found: false
/** `no_flag` and `no_experiment` mean the key is free to create on; `ambiguous` means it is not. */
reason: 'no_flag' | 'no_experiment' | 'ambiguous'
feature_flag_key: string
message: string
/** Set for `ambiguous`: the experiments sharing the flag, none of which stands out as the live one. */
candidates?: ExperimentCandidate[]
}
type Result =
| (WithPostHogUrl<Schemas.Experiment> & { variant_screenshot_urls: Record<string, string[]>; found: true })
| ExperimentLookupMiss
type LinkedPick = { experimentId: number } | { candidates: ExperimentCandidate[] }
const toCandidate = (experiment: Schemas.ExperimentBasic, archived: boolean): ExperimentCandidate => ({
id: experiment.id,
name: experiment.name,
status: experiment.status ?? null,
archived,
start_date: experiment.start_date ?? null,
end_date: experiment.end_date ?? null,
created_at: experiment.created_at ?? null,
})
/** Among several experiments on one flag, the single live one wins, then the single archived one. */
const pickLinkedExperiment = async (context: Context, projectId: string, flagId: number): Promise<LinkedPick> => {
const listLinked = async (archivedOnly: boolean): Promise<Schemas.ExperimentBasic[]> => {
const page = await context.api.request<Schemas.PaginatedExperimentBasicList>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(projectId)}/experiments/`,
query: { feature_flag_id: flagId, limit: 50, ...(archivedOnly && { archived: true }) },
})
return page.results ?? []
}
const live = await listLinked(false)
if (live.length === 1) {
return { experimentId: live[0]!.id }
}
const archived = await listLinked(true)
if (live.length === 0 && archived.length === 1) {
return { experimentId: archived[0]!.id }
}
return {
candidates: [
...live.map((experiment) => toCandidate(experiment, false)),
...archived.map((experiment) => toCandidate(experiment, true)),
],
}
}
const experimentGetByFlagKey = (): ToolBase<typeof schema, Result> => ({
name: 'experiment-get-by-flag-key',
schema,
handler: async (context: Context, params: Params) => {
const key = params.feature_flag_key.trim()
if (key === '') {
throw new ToolInputValidationError('Provide the feature flag key of the experiment to fetch.')
}
const projectId = await context.stateManager.getProjectId()
const flagMatches = await resolveFlagsByKey(context, projectId, key)
if (flagMatches.length === 0) {
return {
found: false,
reason: 'no_flag',
feature_flag_key: key,
message:
`No feature flag with key "${key}" exists in this project, so no experiment is linked to it. ` +
'Create one with `experiment-create`, or call `experiment-list` to browse existing experiments.',
}
}
if (flagMatches.length > 1) {
const ids = flagMatches.map((flag) => flag.id).join(', ')
throw new ToolInputValidationError(
`Multiple feature flags matched key "${key}" (IDs: ${ids}). Call \`experiment-list\` with the ` +
"right `feature_flag_id`, then pass the experiment's numeric `id` to `experiment-get`."
)
}
const flag = flagMatches[0]!
const experimentIds = flag.experiment_set ?? []
if (experimentIds.length === 0) {
return {
found: false,
reason: 'no_experiment',
feature_flag_key: key,
message:
`Feature flag "${key}" (ID ${flag.id}) exists but no experiment is linked to it. ` +
'Create one with `experiment-create` using this key, or call `experiment-list` to browse existing experiments.',
}
}
let experimentId = experimentIds[0]!
if (experimentIds.length > 1) {
const pick = await pickLinkedExperiment(context, projectId, flag.id)
if ('candidates' in pick) {
return {
found: false,
reason: 'ambiguous',
feature_flag_key: key,
candidates: pick.candidates,
message:
pick.candidates.length > 0
? `${pick.candidates.length} experiments are linked to feature flag "${key}" (ID ${flag.id}) and ` +
'none stands out as the live one. Pick from `candidates` and pass its `id` to `experiment-get`.'
: `Feature flag "${key}" (ID ${flag.id}) lists experiments ${experimentIds.join(', ')}, but none ` +
'came back from the experiments list. Try `experiment-get` with one of those ids.',
}
}
experimentId = pick.experimentId
}
const experiment = await context.api.request<Schemas.Experiment>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(projectId)}/experiments/${encodeURIComponent(String(experimentId))}/`,
})
const experimentWithUrl = await withPostHogUrl(context, experiment, `/experiments/${experiment.id}`)
return {
...withConditionIds(withVariantScreenshotUrls(experimentWithUrl, context.api.publicBaseUrl)),
found: true,
}
},
})
export default experimentGetByFlagKey