edit_agent_config

Creates, updates, enables, disables, or deletes an AI Agent’s settings, and triggers test runs. Changes apply immediately.

Settings are the entities that support measuring and testing an Agent rather than changing how it behaves. Edits to Agent behavior — knowledge articles, coaching, Playbooks, Actions, and custom instructions — are staged on a change set through edit_agent_behavior instead.

This tool was previously named propose_change. Behavior entities were moved to edit_agent_behavior so that changes affecting live conversations are staged and tested before going live.

Call get_improvement_guide before proposing changes so the assistant chooses the right entity type and follows Ada’s recommended improvement workflow.

Example prompts

“Create a test case from this failed conversation so we catch regressions on the refund flow.”
“Run tests for all my billing-related test cases.”
“Run my refund test cases against the change I just staged.”
“Create a knowledge source called ‘HR Policies’ so I can file our SharePoint documents into it.”
“Make every article imported into ‘HR Policies’ visible only to end users whose country is US.”
“Create a knowledge source called ADA that imports the single page ada.cx, refreshes weekly, and is only available to end users whose language is French.”
“Create a yes/no variable called wants_callback so my Playbook can route on it.”

Parameters

Parameter	Type	Description
`entity_type`	string	The entity to change.
`operation`	string	What to do. Valid operations depend on `entity_type`.
`entity_id`	string	Required for `update` and `delete`. The ID of the target entity.
`fields`	object	Omit to discover the fields available for an `entity_type` and `operation`. Required for operations that need field values. Keys must match the schema the tool returns.
`confirmed`	boolean	Omit or `false` to receive a preview of the change. Set to `true` only after the change has been explicitly approved.

Supported entity types

Entity type	Covers
`test_case`	Test cases used to evaluate Agent responses.
`test_run`	Execution of one or more test cases.
`topic`	Conversation topics.
`intent`	Intents.
`custom_metric`	Custom metrics.
`scorecard`	Scorecards.
`glossary_term`	Custom Glossary terms.
`knowledge_source`	Knowledge sources that group articles on the Knowledge page. Create a Knowledge API source or a website import, or update a source’s settings.
`variable`	Global variables that Playbooks, tools and availability rules reference. Create only.

The entity types offered depend on which features are enabled for the Agent. Call the tool without fields to see the fields available for a given entity type and operation, and use send_feedback if a capability you need is missing.

Calling an unsupported entity_type and operation combination returns an explicit “not supported” error.

Test cases

Each test case describes how the AI Agent should respond to a specific scenario and what evaluation criteria determine a pass or fail.

Field	Type	Required	Description
`name`	string	Yes (create)	Descriptive name for the test case. Max 256 characters.
`user_message`	string	Yes (create)	The simulated user message sent to the Agent. Max 1024 characters.
`success_criteria`	array of strings	Yes (create)	Criteria used to evaluate the Agent’s response. At least one required. Each criterion is evaluated independently. Max 2048 characters per criterion.
`language`	string	Yes (create)	Language code for the test case (for example, `en`, `fr`).
`channel_id`	string	No	Channel ID to run the test on. Use `list_entities` with `entity_type='channels'` to find IDs.
`variables`	array	No	Variable overrides, as objects with `variable_id` and `value`. Use `list_entities` with `entity_type='variables'` to find IDs.
`scenario_goal`	string	Conditional	The end user’s goal for a multi-turn conversation (for example, “Return a jacket I bought last week”). When provided, the test simulates a full multi-turn exchange instead of a single-turn exchange. Requires the multi-turn simulations feature.

On update, every field is optional. Pass the test case ID via entity_id. On delete, no fields are needed — pass only entity_id.

Test runs

Creating a test_run triggers execution for the specified test case IDs. Use get_test_runs afterward to retrieve pass/fail status, evaluation criteria outcomes, and rationale.

Field	Type	Required	Description
`test_case_ids`	array of strings	Yes	IDs of the test cases to execute. Use `get_test_cases` to find existing test cases, or create them with this tool first.
`changeset_id`	string	No	Runs the tests against a change set instead of the live Agent. Every entity in the simulated conversation uses the staged values, so the test exercises the proposed Agent rather than the live one. Omit to test against the live Agent.

changeset_id belongs inside fields, alongside test_case_ids. One test run targets one change set. Find change set IDs with list_agent_changesets.

Simulations shows each test case’s latest result across live and change set runs. Retrieve their results with get_test_runs.

Knowledge sources

A knowledge source groups articles on the Sources tab of the Knowledge page. Create one here, then file articles into it with edit_agent_behavior by passing its id as knowledge_source_id. Articles authored without a knowledge_source_id land in the default source, Created in Ada. Pass start_urls to create a website import instead: Ada scrapes the URLs into articles and re-crawls them on sync_frequency.

Field	Type	Required	Description
`name`	string	Yes	Display name shown on the Knowledge page. Names are case-sensitive and unique per Agent — `HR Policies` and `hr policies` are two different sources. Check `list_entities` with `entity_type='knowledge_sources'` first to reuse an existing source instead of creating a near-duplicate.
`external_id`	string	No	Your own stable identifier for the source, 1–160 characters. This is the ID the Knowledge API addresses the source by. Defaults to the source’s Ada ID when omitted. A value another source on the Agent already uses is refused.
`metadata`	object	No	Arbitrary key/value pairs for your own bookkeeping. Ada does not read them. Knowledge API sources only.
`start_urls`	array of objects	No	Makes the source a website import. Each entry has a `url` (http or https) and `crawl`: `true` follows the links on the page and imports the pages it finds, `false` imports that page only (the default). The first import starts right away. `external_id` and `metadata` do not apply to a website import.
`sync_frequency`	string	No	How often a website import re-crawls its URLs: `daily`, `weekly` (the default) or `never`. Only with `start_urls`.
`availability_rules`	object	No	Availability rules that the Knowledge API, Apps and website imports copy onto every article they later create under this source whose request omits its own rules. Articles written through `edit_agent_behavior` are not covered. Articles that already exist keep their rules when the source’s rules change. Not allowed on Created in Ada. Same schema as an article’s rules; see Availability rules.

The response returns the new source’s id, name, external_id, status, last_sync, and metadata, plus availability_rules when the request sent it. Use id with Ada MCP tools and external_id with the Knowledge API.

Update a source

update takes the source’s Ada id as entity_id. The fields it accepts depend on how the source was created:

Source	`name`	`sync_frequency`	`availability_rules`
Website import	Yes	Yes: `daily`, `weekly` or `never`	Yes
Knowledge API	Yes	No	Yes
App, such as Zendesk or Salesforce Knowledge	No	No	Yes
Created in Ada	No	No	No

A field the source does not accept is refused before the confirmation step, with a message that names the source type. An App source keeps the name its App gave it. For availability_rules, send a rule object to set the rules or null to clear them. Articles that the Knowledge API, Apps and website imports create under the source after the change get the new rules; existing articles keep theirs.

Delete a source through the Knowledge API. Deleting a source removes every article in it, so it is deliberately not exposed here.

Variables

A global variable holds a value for the whole conversation. Playbook set, ask and if_else steps, tool output bindings and availability rules reference it by id. Create the variable here, then use its id in edit_agent_behavior. Check list_entities with entity_type='variables' first to reuse an existing variable.

Field	Type	Required	Description
`name`	string	Yes	The variable’s name, unique among the Agent’s global variables.
`type`	string	No	The kind of value the variable holds: `text`, `number` or `yes/no`. Defaults to `text`. The type is fixed after creation.
`description`	string	Yes	What the variable holds and when it is set. Shown on the Variables page.

The response returns the new variable’s id, name, scope, type and description.

Only global scope is supported. Rename or delete a variable from the Variables page in the dashboard. A rename or a delete changes every Playbook and rule that references the variable, so neither is exposed here.