> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Config assistant: propose changes in plain language

> Describe how an agent should behave and the config assistant returns a proposed partial diff (field, new value, one-line reason) for your review. Nothing is applied until you accept it and save.

# Config assistant

`POST /api/v1/agents/{id}/config-assistant` takes a natural-language description of how an agent should behave and returns a **proposed** set of configuration changes: one entry per field, each with the field name, the new value, and a one-line reason. It applies nothing. Reviewing the proposal and saving it (or not) stays entirely in your hands, through the normal save path.

This page covers what the endpoint proposes, what it refuses to touch, and how a proposal becomes a saved change. For building a **new** agent from a plain-language prompt, see [Build an agent from a prompt](https://docs.orbit.devotel.io/guides/agent-from-prompt.md); the config assistant instead edits an **existing** agent, and only ever by proposal.

## What it does

Send an `instruction` of 3 to 4,000 characters describing the behaviour you want:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_abc123/config-assistant \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Make the agent more concise and cap responses at 120 tokens."
  }'
```

The response (in the standard `data` envelope) carries three things:

* `changes`: the proposed diff. Each entry names a `field`, the proposed `value`, and a one-line `rationale`.
* `summary`: one sentence describing the proposal as a whole.
* `rejected`: any suggestion the assistant made but that failed validation, with the reason it was dropped.

Applying is a separate step. The endpoint never writes to the agent. Accept the proposal in the dashboard, or send the same values yourself through `PUT /api/v1/agents/{id}`, which runs all of its usual validation.

## Why partial diffs

The response lists only the fields the assistant wants to change. Returning the whole configuration would make every untouched field look like a change you have to re-approve, and an unnoticed edit can slip through review fatigue. With a partial diff, every row is a real decision. A single proposal carries at most six changes; split a longer instruction into multiple calls.

## What it will never touch

* **`model` is out of scope.** Model selection is your own cost-versus-capability call (see [Model selection](https://docs.orbit.devotel.io/agents/model-selection.md)), so the assistant can never propose it.
* **Only fields the configuration form renders.** The proposal set is closed: `systemPrompt`, `temperature`, `maxTokens`, and `tools`. Every proposed value is something you could have entered in the form yourself; anything else is dropped and listed in `rejected`.
* **Nothing applies automatically.** There is no silent-rewrite mode. A proposal you do not accept changes nothing.
* **No invented tools.** A proposed `tools` change keeps only tool ids your workspace actually offers; unknown ids are dropped with a `no such tool` reason.

The endpoint requires the `owner`, `admin`, or `developer` role; other roles receive `403`.

## Saveability guarantees

Every proposed value is validated against the same bounds the configuration form enforces, before it reaches you, so each row of a proposal you accept is saveable:

| Field | Guarantee | Example |
| - | - | - |
| `systemPrompt` | Shorter than 10 characters is dropped; longer than 10,000 characters is clipped to 10,000. | A 12,000-character draft becomes a 10,000-character proposal. |
| `temperature` | Clamped to 0 to 2. | A proposal of `3` becomes `2`. |
| `maxTokens` | Rounded to a whole number and clamped to 64 to 8,192. | A proposal of `120.4` becomes `120`; `20000` becomes `8192`. |
| `tools` | Filtered to registered tool ids; duplicates removed. | `["search_knowledge", "no_such_tool"]` becomes `["search_knowledge"]`. |

When a suggested change cannot be repaired into a saveable value, it is not surfaced as a broken proposal: it appears in `rejected` with the reason, and the rest of the proposal stands.

## Review flow in the dashboard

1. Open the assistant panel beside the agent's configuration form and describe the change you want.
2. The reply appears as a proposal card next to the form: one row per proposed field, each with its reason, plus the one-sentence summary.
3. Accept a row to stage its value into the matching form field, or discard it to leave the field as is.
4. Press **Save** as usual. Saving goes through the same `PUT /agents/{id}` validation as a hand edit, and nothing persists until you do.

Closing the panel or leaving the page drops any proposal you have not accepted.

## Worked example

Instruction: *"make the agent more concise and cap responses at 120 tokens."*

The assistant reads the agent's current configuration and returns this diff:

| Field | Proposed value | Rationale |
| - | - | - |
| `systemPrompt` | The current instructions plus an explicit rule to keep answers brief (at most three sentences). | Adds the brevity rule to the instructions themselves. |
| `maxTokens` | `120` | Caps reply length at the number you asked for. |

`model`, and every other field, is untouched. To apply the same change through the API instead of the dashboard, send those values with the regular update call:

```bash theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agent_abc123 \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a customer support agent for Acme Corp. Answer briefly, in at most three sentences. If you cannot resolve an issue, offer to transfer to a human agent.",
    "max_tokens": 120
  }'
```

## Errors

* `422` — the `instruction` is missing, shorter than 3 characters, or longer than 4,000 characters.
* `403` — the key's role is not `owner`, `admin`, or `developer`.
* `404` — the agent id does not exist in your workspace.
* `429` — too many agent invocations in a short window; wait a moment and retry.
* `503` — the assistant could not produce a proposal right now. Try again, or edit the fields directly; nothing changed in the meantime.

## Related

* [Creating agents](https://docs.orbit.devotel.io/agents/creating-agents.md): the create-to-deploy walkthrough, including the configuration fields the assistant can propose.
* [Model selection](https://docs.orbit.devotel.io/agents/model-selection.md): why `model` stays your call.
* [The Agents workspace map](https://docs.orbit.devotel.io/guides/agents-hub-overview.md): orientation for the `/agents` hub.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.