edit_agent_behavior

Edits what an AI Agent knows, says, or does. Every edit is staged on a change set — a bundle of changes that is not live until it is promoted.

This is the only way to change Agent behavior through the MCP server. Settings such as test cases and topics are edited with edit_agent_config, which applies immediately.

Call get_improvement_guide first, and describe_entity before each edit — it returns the editable fields for an entity type along with the rules that apply to it.

Example prompts

“Our return window is 30 days now — update the returns article, test it, and publish it if it looks right.”
“Change step 2 of the returns Playbook and the supporting article together, then run my regression tests against both.”
“What behavior changes are staged right now?”
“That last change is causing confusion — roll it back.”

How a change reaches production

The same loop every time: draft, test, promote, revert.

Draft. Describe the AI Agent behavior you would like to change, or the ideal experience you want to build. The MCP assistant decides which entities to edit or create, stages the edit on a change set, and nothing goes live. Related edits can be added to the same change set so they test and ship together.
Test. Run simulations against the change set. The simulated conversation uses the staged edits while the live Agent stays untouched.
Promote. The assistant shows what will change and any warnings. Nothing goes live until this is explicitly confirmed.
Revert. Reverse a promoted change, restoring the entities to how they were before.

A promoted change set can be reverted for up to 90 days after it was promoted. Deleting a promoted change set means it can no longer be reverted.

Testing is strongly recommended but not required — a change set can be promoted without it.

Parameters

Parameter	Type	Description
`operation`	string	Required. One of `describe_entity`, `update`, `remove`, `promote`, `revert`, `delete`.
`entity_type`	string	Required for `describe_entity`. Optional for `remove`, where it defaults to `knowledge_article`.
`name`	string	Required for `update` when `changeset_id` is omitted. A short label for the change set, shown in `list_agent_changesets`. Describe the shared purpose of the bundle rather than any single edit.
`changeset_id`	string	Required for `promote`, `revert`, `remove`, and `delete`. Optional for `update` — supply it to add to an existing change set, omit it to start a new one.
`changes`	array	For `update`. The edits to stage. Each edit is keyed on its entity, so resubmitting the same entity replaces its staged edit rather than adding a second one.
`entity_id`	string	Required for `remove` — the entity whose staged edit is withdrawn. For `update`, `entity_id` belongs inside each entry of `changes`.
`change_type`	string	Optional for `describe_entity`. `created` returns the fields available when creating; `modified` returns the fields available when updating, which is a smaller set for some entities.
`confirmed`	boolean	Set only after the change has been explicitly approved. Required for `promote`, `revert`, and `delete`.

Each entry in changes is a created, modified, or deleted change. modified is a partial update — fields that are not supplied keep their live values.

Operations

Operation	What it does
`describe_entity`	Returns the editable fields and rules for an entity type.
`update`	Stages one or more edits, creating a change set if none is supplied.
`remove`	Withdraws a single edit from a change set, leaving its other edits in place.
`promote`	Makes a change set live, once approved.
`revert`	Reverses a promoted change set, once approved.
`delete`	Discards a change set that has not been promoted.

What you can change

`entity_type`	Covers
`knowledge_article`	Knowledge articles created in Ada.
`coaching`	Coaching anchored to a specific Agent turn.
`playbook`	Playbooks built from sections and steps.
`api_tool`	Actions backed by an HTTP request.
`custom_instruction`	Custom instructions.

Greetings, handoffs, processes, and CSAT surveys are not covered and continue to be edited in the Ada dashboard.

Rules that apply to each type

These are enforced when an edit is staged, so an edit that breaks one is rejected before it reaches a change set. describe_entity returns the rules for the type requested.

Knowledge articles — only articles created in Ada are editable. Articles imported from another knowledge source, such as Zendesk, Salesforce, or a web import, are read-only and must be edited in the system they came from.

Coaching — coaching is always anchored to a single Agent turn in a conversation. Take the conversation and event identifiers from a get_conversation response where the entry is marked as coachable. The anchor and the coaching type cannot be changed afterward — to change the type, delete the coaching and create it again. Coaching types that act on a specific target, such as an Action or a Playbook, require that target to be identified. Coaching copied from another Agent is read-only.

Playbooks — only Playbooks built from sections and steps are editable; older Playbooks Classic entries are not. If a live Playbook contains send-step attachments, its sections cannot be edited here, though its name, description, and general instructions still can. Every staged Playbook is validated the same way the dashboard validates a Playbook on save, so an incomplete Playbook cannot be staged.

Actions — the name, description, enabled state, and direct-use setting can be changed. The request itself, along with the input and output schemas, forms the contract with any Playbook that uses the Action, so those are not editable — changing them in place would break those Playbooks silently. Create a new Action instead.

Availability rules are not set through change sets. They are configured in the Ada dashboard, and are preserved when a change set is promoted or reverted.

Limits

Limit	Value
Entities changed per change set	10
Active change sets per Agent	5
Change sets per test run	1

Reaching a limit returns an explanation. Promote, revert, or delete an existing change set to free capacity.

Approval before anything goes live

Promoting, reverting, or discarding a change set always pauses for approval. The assistant shows what will change and any warnings, then waits for explicit confirmation before applying it. This cannot be skipped, even by asking the assistant to publish without confirming.

If the live Agent changes again between the summary and the approval, the assistant checks again and shows an updated summary rather than applying something that was never reviewed.

When two edits clash

More than one person can work on the same Agent, and the live Agent can change while a change set is being staged. Before a change set goes live it is checked against the live Agent, and any conflict is surfaced as a warning. Conflicts are never merged automatically and never applied silently.

Edits to different fields of the same entity both survive. Edits to the same field are resolved in favor of whichever change set is promoted last.

Warnings appear in the approval summary and do not block promotion:

Warning	What it means
A newer change would be overwritten	The same field was changed on the live Agent after the edit was staged. The warning names the fields and shows their current live values.
The target is gone	The entity being changed was deleted from the live Agent.
A reference is broken	A Playbook step or coaching entry points at something that is no longer live.
A reference could not be checked	The verification did not complete, so treat the reference as unconfirmed.

When warned, there are three ways forward: promote anyway and let the staged version win, ask the assistant to rebuild the edit on top of the current live version and then promote, or discard the edit and keep what is live. The change set is preserved in all three cases.

Promoting and reverting

Promotion is all-or-nothing. Every staged edit is applied together, and if any part fails the whole change set is rolled back. One change set is promoted at a time per Agent, so a promotion attempted while another is in progress is rejected and can be retried.

Only a promoted change set can be reverted. A preview is available first, listing the entities the revert will restore, so it is clear what is being approved.

Reverting changes those entities straight back to their state before the change set was promoted, and takes effect as soon as it is approved — there is no separate test step for a revert. Any edit made to those entities after promotion is overwritten.

Reverting and deleting are different. Reverting reverses a live change. Deleting discards a change set and reverses nothing — and once a promoted change set is deleted it can no longer be reverted, so use revert to undo a live change.

Change sets are promoted within a single Agent. A change set cannot be moved between instances.

Retention

Change sets are kept until they are deleted. A promoted change set stays revertible for 90 days after it was promoted; after that it can no longer be reverted.

Where to see results

Change sets are managed and viewed entirely through the MCP server. There is no change sets screen in the Ada dashboard.

Test runs pinned to a change set do not appear on the Simulations page in the dashboard, which stays focused on live, user-initiated runs. Retrieve their results with get_test_runs, and use list_agent_changesets to see what is staged, promoted, or reverted.