update_agent
Destructive
Update an existing Convocore agent (PATCH). For large prompt edits prefer patch_agent_prompt. Main prompt: use systemPrompt → start node instructions. NEVER send vg_instructions or vg_systemPrompt. Do NOT pass nodes[] unless you are changing nodes — omit it for title/UI/funnel/model updates. Partial nodes[] are GET-merged by id; a toolsIds-only start node cannot blank instructions, and toolsIds in a patch are only ever ADDED (tools attached on the dashboard are kept). To detach tools pass allowRemoveTools=true. Lead notify: funnelConfig (steps + notificationRules.recipients). UI Engine: vg_enableUIEngine* + vg_uiEngineChannelConfig. ownerID is read-only.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"agentId": "<agentId>"
},
"name": "update_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| light | No | Updated light mode setting | |
| nodes | No | Node patch. MCP merges onto the current graph by node id so partial updates (e.g. toolsIds) cannot blank nodes[0].instructions. Prefer systemPrompt for prompt writes. | |
| theme | No | Updated theme | |
| title | No | Updated title | |
| agentId | Yes | The unique identifier of the agent to update | |
| disabled | No | Updated disabled status | |
| description | No | Updated description | |
| voiceConfig | No | Agent voiceConfig for voice-capable agents. Integrations/API keys generally live at workspace/org level; this config selects providers, models, voices, and call behavior for the agent. | |
| enableVertex | No | Updated Vertex AI setting | |
| funnelConfig | No | AI Funnel & Lead Scoring (built-in). Use this instead of a custom HTTP “notify sales team” webhook. enabled + steps (id/name/description/condition/points/category) + notificationRules (type score_threshold|steps_completed|data_collected, recipients emails, cooldownStrategy). Runtime scores the conversation and emails recipients when a rule fires. | |
| systemPrompt | No | Replace main prompt → nodes[0].instructions (enableNodes forced true). Prefer patch_agent_prompt for surgical edits. | |
| autoOpenWidget | No | Updated auto-open widget setting | |
| additionalConfig | No | Every other agent field the API accepts, typed from the main agent schema. Send only what changes: nested objects (nodesSettings, vg_kb_llm, ui…) are deep-merged into the current value, so existing settings are kept. Do not put the main prompt here (use systemPrompt / patch_agent_prompt). Unknown fields are rejected up front with the valid names. | |
| vg_enableUIEngine | No | MASTER SWITCH for UI Engine. When true the agent can emit structured UI (text, choice/buttons, visual, cardV2, carousel, iFrame, and — if their flags are on — form/input, invoice, calendarBooking). Call get_ui_engine_spec for payloads. Prefer enabling this before toggling individual elements. | |
| leadCollectionRules | No | When to persist a CRM lead. Default: collect when email, phone, or phone_number is present. | |
| vg_maxImagesPerCard | No | Max images per cardV2/carousel card: 1 = imageUrl only; 2–3 allow images[] gallery. Omit for platform default. | |
| vg_enableUIEngineForms | No | Allow form + input UI Engine elements (typically web). Set true to let the agent collect structured fields. Also set vg_uiEngineChannelConfig.web.form / .input as needed. | |
| vg_enableUIEngineInvoice | No | Allow invoice card UI Engine elements (web). Use with vg_uiEngineInvoiceConfig for click notifications. | |
| vg_uiEngineChannelConfig | No | Per-channel allowlist of which UI Engine elements the agent may show. Channels: web, whatsapp, instagram, messenger, telegram. Each channel is an object of type→boolean (choice, visual, cardV2, carousel, iFrame, form, input, invoice, calendarBooking, file, VoiceNote, locationRequest, ctaUrl). Missing type = enabled. Example: { "web": { "choice": true, "cardV2": true, "form": true, "invoice": false }, "whatsapp": { "choice": true, "cardV2": true, "form": false } }. Forms/invoice/calendar still need their global vg_enableUIEngine* flags. | |
| vg_uiEngineInvoiceConfig | No | Invoice card notification settings. | |
| vg_uiEngineCalendarConfig | No | Calendar booking widget config (Google Calendar connection + booking rules). | |
| vg_uiEngineFormNotifyConfig | No | Email notify settings when forms/inputs are submitted. | |
| vg_enableUIEngineCalendarBooking | No | Allow interactive calendar booking widget (web). Requires Google Calendar connectionIds in vg_uiEngineCalendarConfig. |