An audit trail for agent flag changes
When AI agents change feature flags, you need to know which agent made each change, in which run and why. Flagger.gg records every change with the actor (a person, a named agent token, the code registry or an import), the run, a note, the state and rules before and after, the client and the IP. Agent tokens can't write without a note, and the org audit log filters by agent, flag, run and person.
Updated
What each change records
| Field | What it holds |
|---|---|
| Actor | Who: a person (name and email), an agent token by its name (for example "Checkout agent"), an admin token, the code registry, an import or the system. |
| Run | Which run of the agent: an id and an optional URL, such as the agent's thread or CI job. |
| Note | Why, in the agent's or person's words. Required for agent tokens. |
| From and to | The state and rules before and after the change. |
| Client | Where it came from: console, cli, mcp, api or sdk. |
| IP | The address the change was made from. |
| Request | For an approved change, the approval request it came from, so you can see who asked and who approved. |
Each flag also keeps its own history: changes, the code registry creating it, imports and approvals, newest first.
How the run gets recorded
Agents often run many sessions in parallel, so "an agent changed it" isn't enough; you want the session. Flagger.gg takes the run from, in order:
- the
runinput on an MCP tool, or--run id [url]on the CLI; - the
FLAGGER_RUNenvironment variable (CLI and stdio MCP), or theX-Flagger-Runheader over HTTP; - for MCP, failing both, the client's name from
initialize.
Put a link to the agent's thread or job in the run's URL, and the audit row leads straight back to the conversation that made the change.
Find a change
- Console: the org audit log at
/auditfilters by project, environment, flag, agent, person and run, and every filter is in the URL, so a filtered view can be shared. A flag's drawer has a History tab. Times are shown in 12-hour Eastern. - CLI:
flagger get <key>prints a flag with its history and pending requests. - API:
GET /v1/audittakesproject,env,flag,agent(token id or name),actor(email),runandaction, up to 200 entries a page with a cursor.
Undo what an agent did
Once you've found the change, flagger revert <key> (or the flag_revert tool) puts back the state before the latest change, and --to <event id> goes back to any point in the history. If you need it off now, kill it. Both are recorded too.
Guardrails next to the log
An audit trail tells you what happened. These decide what can happen:
- Agent tokens are scoped to one project, a list of environments and a set of actions, expire after 90 days and can be revoked.
- With approvals on, an agent in production can roll out up to a cap (10% by default) on its own; wider changes become requests a person approves. There is no approve tool for agents.
- Protected flags refuse agents except for kill.
- Agent tokens are limited to 30 writes a minute, and with approvals on, 5 changes to one flag an hour. Kill is exempt.
User ids and emails of the people using your app never reach Flagger.gg, because flags are evaluated inside your app. The log holds changes to flags, not your users' activity.
FAQ
How do I see which AI agent changed a feature flag?
Open the audit log in the Flagger.gg console and filter by flag. Each row names the agent token, the run, the note, and the state before and after.
Can an agent change a flag without saying why?
No. Writes from agent tokens without a note are refused, over the API, the CLI and MCP.
Can I see everything one agent session did?
Yes, if the agent passes a run id. Filter the audit log by run to see every change that run made.
Does the audit log include my users' data?
No. Flags are evaluated inside your app, so your users' ids and emails never reach Flagger.gg. The log only holds targeting lists that people or agents typed into a flag.
Ship your next change behind a flag.
Sign up, add an SDK key to your app and give your agent a token.