Skip to main content

​
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; 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:
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), 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: 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: 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:

​
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.