> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # 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`](/mcp/tools/edit-agent-behavior) instead. > **Note** > > This tool was previously named `propose_change`. Behavior entities were moved to [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) so that changes affecting live conversations are staged and tested before going live. Call [`get_improvement_guide`](/mcp/tools/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`](/mcp/tools/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`](/mcp/tools/list-entities) with `entity_type='channels'` to find IDs. | | `variables` | array | No | Variable overrides, as objects with `variable_id` and `value`. Use [`list_entities`](/mcp/tools/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`](/mcp/tools/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`](/mcp/tools/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`](/mcp/tools/list-agent-changesets). **Simulations** shows each test case's latest result across live and change set runs. Retrieve their results with [`get_test_runs`](/mcp/tools/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`](/mcp/tools/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`](/mcp/tools/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](/reference/knowledge/sources) 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`](/mcp/tools/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](/reference/introduction/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](/reference/knowledge/sources). 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`](/mcp/tools/edit-agent-behavior). Check [`list_entities`](/mcp/tools/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.