Update Agent

Updates an agent, this route must use the new V3 endpoints.

PATCH /agents/{id}

Update Agent

cURL

curl --request PATCH \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": "<unknown>"
}
'

200

{
  "success": true,
  "message": "<string>",
  "data": {
    "title": "<string>",
    "description": "<string>",
    "ownerID": "<string>",
    "theme": "<string>",
    "voiceConfig": {
      "transcriber": {
        "speechConfig": {
          "format": "<string>",
          "sampleRate": 123,
          "language": "<string>"
        },
        "modelId": "<string>",
        "patienceFactor": 123,
        "language": "<string>",
        "randomOptions": "<unknown>",
        "internal": {
          "inputAudioStream": "<unknown>",
          "debug": true
        },
        "apiKey": "<string>",
        "platformSpecific": {
          "deepgram": {
            "keywords": [
              "<string>"
            ],
            "language": "<string>",
            "smart_format": true,
            "model": "<string>",
            "interim_results": true,
            "endpointing": 123,
            "no_delay": true,
            "autoLanguageDetection": true
          },
          "assemblyai": {
            "modelId": "<string>"
          },
          "googleCloud": {
            "keywords": [
              "<string>"
            ],
            "model": "<string>",
            "languageCode": "<string>",
            "enableAutomaticPunctuation": true,
            "enableWordTimeOffsets": true,
            "maxAlternatives": 123,
            "profanityFilter": true,
            "speechContexts": [
              {
                "phrases": [
                  "<string>"
                ],
                "boost": 123
              }
            ]
          }
        },
        "utteranceThreshold": 123,
        "inputVoiceEnhancer": true
      },
      "speechGen": {
        "highAudioQuality": true,
        "modelId": "<string>",
        "voiceId": "<string>",
        "apiKey": "<string>",
        "region": "<string>",
        "punctuationBreaks": [
          "<string>"
        ],
        "platformSpecific": {
          "elevenLabs": {
            "stability": 123,
            "similarity_boost": 123,
            "use_speaker_boost": true,
            "speed": 123,
            "style": 123
          },
          "playht": {
            "voiceId": "<string>"
          },
          "cartesia": {
            "speed": 123,
            "volume": 123,
            "promptInstructions": "<string>"
          },
          "ultravox": {
            "temperature": 0.5,
            "vadSettings": {
              "turnEndpointDelay": "<string>",
              "minimumTurnDuration": "<string>",
              "minimumInterruptionDuration": "<string>",
              "frameActivationThreshold": 0.55
            }
          }
        },
        "backChannelling": true,
        "language": "<string>",
        "enableLongMessageBackchannelling": true,
        "backchannelMessages": [
          "<string>"
        ],
        "backchannelInterval": 123,
        "wordsReplacements": [
          {
            "word": "<string>",
            "replacement": "<string>"
          }
        ],
        "internal": {
          "inputTextStream": "<unknown>",
          "audioConfig": {
            "format": "<string>",
            "sampleRate": 123,
            "channels": 123,
            "language": "<string>"
          },
          "emitOnComplete": true
        }
      },
      "config": {
        "recordAudio": true,
        "enableWebCalling": true,
        "firstInputChunkUNIXMs": 123,
        "firstOutputChunkUNIXMs": 123
      }
    },
    "light": true,
    "enableVertex": true,
    "autoOpenWidget": true,
    "createdAtUNIX": 123,
    "disabled": true,
    "vectorDb": "<unknown>",
    "withRefresh": true,
    "agentPlatform": "<string>",
    "ID": "<string>",
    "storageID": "<string>",
    "VF_DIALOGUE_API_KEY": "<string>",
    "VF_PROJECT_API_KEY": "<string>",
    "VF_PROJECT_ID": "<string>",
    "VF_KB_API_KEY": "<string>",
    "roundedImageURL": "<string>",
    "rectangeImageURL": "<string>",
    "messageDelayMS": 123,
    "scrollAnimation": true,
    "proactiveMessage": "<string>",
    "acceptFileUpload": true,
    "recordChatHistory": true,
    "chatBgURL": "<string>",
    "disableSmoothScroll": true,
    "isDeployed": true,
    "tokensUsage": "<unknown>",
    "maxTokensUsage": "<unknown>",
    "lastModified": 123,
    "fontFamily": "<string>",
    "branding": "<string>",
    "customThemeJSONString": "<string>",
    "autoStartWidget": true,
    "allTimeTriggers": 123,
    "syncBrowser": true,
    "delayBeforeSubmit": 123,
    "listenForUrlChanges": true,
    "chatForget": true,
    "lang": "<string>",
    "enableAudioSupport": true,
    "AITranslateTo": "<string>",
    "enableAITranslate": true,
    "disableNoReplyListener": true,
    "disableHumanHandoff": true,
    "alwaysShowHandoff": true,
    "manualControl": true,
    "enableVGHandoff": true,
    "enableGeoAnalytics": true,
    "hideVoiceflowAnalytics": true,
    "hideCallAnalytics": true,
    "hideConversationMetrics": true,
    "hideCustomAnalytics": true,
    "hideVapiAnalytics": true,
    "hideFunnelAnalytics": true,
    "hideHandoffAnalytics": true,
    "fixedHandoffPopup": true,
    "ADVANCED_customCSS": "<string>",
    "messagesLimit": 123,
    "whatsappToken": "<string>",
    "whatsappNumberId": "<string>",
    "whatsappBusniessId": "<string>",
    "whatsappCustomBridge": {
      "enabled": true,
      "webhookUrl": "<string>",
      "forwardToDeveloper": true
    },
    "waTestNumber": "<string>",
    "waVerifyPassed": true,
    "waTestPassed": true,
    "twilioSmsAccountSid": "<string>",
    "twilioSmsAuthToken": "<string>",
    "twilioSmsPhoneNumber": "<string>",
    "twilioSmsVerified": true,
    "twilioSmsPhoneNumberSid": "<string>",
    "twilioSmsRentalSubscriptionId": "<string>",
    "webhookUrl": "<string>",
    "gcloudPrivateKey": "<string>",
    "gcloudClientEmail": "<string>",
    "smartInit": true,
    "UIhandoffTitle": "<string>",
    "UIhandoffSubtitle": "<string>",
    "igVerified": true,
    "igAccessToken": "<string>",
    "showHandoffEvenIfOffline": true,
    "persistHandoffOnRefresh": true,
    "enableBugReporting": true,
    "blockInputDuringHandoffRequest": true,
    "disableHandoffMessages": true,
    "disableHandoffStatusMessages": true,
    "customButtonJSON_STRING": "<string>",
    "vg_initPrompt": "<string>",
    "vg_prompt": "<string>",
    "vg_initMessages": [
      "<string>"
    ],
    "vg_systemPrompt": "<string>",
    "vg_temperature": 123,
    "vg_maxTokens": 123,
    "vg_kbDefaultDimension": 123,
    "vg_kbTopChunks": 123,
    "SECRET_API_KEY": "<string>",
    "vg_kbCharCount": 123,
    "vg_kbDocsNum": 123,
    "vg_enableUIEngine": true,
    "vg_enableAboutContext": true,
    "vg_kb_llm": {
      "searchPrompt": "<string>",
      "temprature": 123,
      "maxTokens": 123
    },
    "vg_enableUIEngineForms": true,
    "vg_max_messages_history": 123,
    "ifKnowsThreshold": 123,
    "avatarImageUrl": "<string>",
    "headerImageUrl": "<string>",
    "bannerImageUrl": "<string>",
    "soundEffectUrl": "<string>",
    "soundEffectEnabled": true,
    "enableQuickFileUpload": true,
    "instagramOptions": {
      "pageId": "<string>",
      "accessToken": "<string>"
    },
    "translateUserResponse": true,
    "starred": true,
    "flowise": {
      "webhookUrl": "<string>",
      "webhookSecret": "<string>"
    },
    "vfSettings": {
      "enableIgnoreUrlPaths": true
    },
    "vapi": "<unknown>",
    "vapiConfig": {
      "syncKbOnSave": true,
      "PUBLIC_API_KEY": "<string>",
      "PRIVATE_API_KEY": "<string>",
      "enableVapiOnWeb": true,
      "overrideWithVG": true,
      "promptOnWeb": true,
      "maxCostMonthly": 123,
      "maxMinutesMonthly": 123,
      "useVfProject": true,
      "syncTools": true
    },
    "vgOptions": {
      "isLlmStudio": true,
      "showSources": true,
      "lightUiEngine": true,
      "legacyKb": true,
      "maxChunkSize": 123,
      "handoffTimeout": 123
    },
    "ui": {
      "showWhatsappButtonOnWeb": true,
      "bgImageVisible": true,
      "enableFixedFeedbackBtns": true,
      "switchConversationSides": true,
      "switchDashboardOnly": true,
      "voice": {
        "question": "<string>",
        "continueBtnLabel": "<string>",
        "dismissBtnLabel": "<string>",
        "disableVoiceOrb": true,
        "voiceOnlyMode": true
      }
    },
    "assignedToolsIds": [
      "<string>"
    ],
    "tools": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "isDefault": true,
        "serverUrl": "<string>",
        "serverUrlSecret": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "disabled": true,
        "isVapiTool": true,
        "vapiId": "<string>",
        "isGlobal": true,
        "variablesIds": [
          "<string>"
        ],
        "agentId": "<string>",
        "userId": "<string>",
        "backchannellingPhrases": [
          "<string>"
        ],
        "toolsSettings": "<unknown>",
        "fields": [
          {
            "id": "<string>",
            "in": "<string>",
            "value": "<unknown>",
            "defaultValue": "<unknown>",
            "key": "<string>",
            "description": "<string>",
            "required": true,
            "reusable": true,
            "isEnv": true,
            "isSystem": true,
            "isGlobal": true,
            "agentId": "<string>",
            "userId": "<string>"
          }
        ],
        "channels": []
      }
    ],
    "internal": {
      "setOnResponse": true,
      "enableSetOnLoad": true
    },
    "disableAutoTranscribeAudio": true,
    "disableTranscriptSharing": true,
    "instaAgentUsername": "<string>",
    "convoTags": [
      "<string>"
    ],
    "vfConfig": {
      "alwaysEnableCardButtons": true
    },
    "discord": {
      "channelIds": [
        "<string>"
      ],
      "webhookUrls": [
        "<string>"
      ]
    },
    "limits": {
      "maxInteractionsPerUserId": 123,
      "maxAnnualCreditsUsage": 123,
      "maxMonthlyCreditsUsage": 123,
      "maxMessages": 123,
      "maxMessagesRetentionDays": 123
    },
    "tabs": [
      {
        "label": "<string>",
        "iconUrl": "<string>",
        "iframeUrl": "<string>",
        "iframeHeight": 123,
        "hide": true,
        "homeSpecific": {
          "buttons": [
            {
              "key": "<string>",
              "label": "<string>",
              "iconUrl": "<string>",
              "show": true,
              "iceBreakers": [
                "<string>"
              ]
            }
          ],
          "iceBreakers": [
            "<string>"
          ],
          "showLiveCall": true,
          "showRecentConvo": true,
          "showDirectHandoff": true,
          "headerHeight": 123,
          "headerTitle": "<string>",
          "headerDescription": "<string>"
        },
        "faqSpecific": {
          "questions": [
            {
              "id": "<string>",
              "question": "<string>",
              "answer": "<string>",
              "key": "<string>"
            }
          ],
          "enableCustomFaq": true
        }
      }
    ],
    "kbTags": [
      "<string>"
    ],
    "kbTagsDataMap": "<array>",
    "nodes": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "instructions": "<string>",
        "llmConfig": {
          "temperature": 123,
          "maxTokens": 123,
          "customModelId": "<string>",
          "serverUrl": "<string>",
          "apiKey": "<string>"
        },
        "language": "<string>",
        "mcpServers": [
          {
            "name": "<string>",
            "url": "<string>",
            "useNodeEventSource": true,
            "reconnect": {
              "enabled": true,
              "maxAttempts": 123,
              "delayMs": 123
            },
            "command": "<string>",
            "args": [
              "<string>"
            ],
            "env": {},
            "cwd": "<string>",
            "headers": {}
          }
        ],
        "voiceInstructions": "<string>",
        "isGlobal": true,
        "toolsIds": [
          "<string>"
        ],
        "toolsSettings": {
          "googleCalendar": {
            "calendarId": "<string>",
            "methods": []
          },
          "googleSheets": {
            "connectionId": "<string>",
            "sheetId": "<string>",
            "method": "<string>",
            "sheetTabName": "<string>",
            "headerRowIndex": 123,
            "headerDescriptions": {},
            "identifierColumn": "<string>",
            "identityFields": {
              "phone": "<string>",
              "email": "<string>",
              "name": "<string>",
              "custom": "<string>",
              "customLabel": "<string>"
            },
            "queryableFields": [
              "<string>"
            ]
          },
          "airtable": {
            "connectionId": "<string>",
            "baseId": "<string>",
            "tableId": "<string>",
            "method": "<string>",
            "fieldDescriptions": {},
            "identifierField": "<string>"
          }
        },
        "childrenNodes": [
          {
            "nodeId": "<string>",
            "condition": "<string>"
          }
        ],
        "routerLlmConfig": {
          "temperature": 123,
          "maxTokens": 123,
          "customModelId": "<string>",
          "serverUrl": "<string>",
          "apiKey": "<string>"
        },
        "toolUseBias": 123,
        "autoRerouter": {
          "enabled": true,
          "level": 123
        },
        "rf": "<unknown>",
        "kb": {
          "enabled": true,
          "maxChunks": 123,
          "tags": [
            "<string>"
          ],
          "smartSearch": true
        },
        "conditionData": {
          "condition": "<string>"
        },
        "preStart": {
          "url": "<string>",
          "enabled": true,
          "testConvoIdValue": "<string>"
        },
        "startConfig": {
          "initialMessage": "<string>",
          "userStarts": true
        }
      }
    ],
    "enableNodes": true,
    "advanced": {
      "serverUrl": "<string>",
      "serverUrlSecret": "<string>"
    },
    "nodesSettings": {
      "enableUIEngineForms": true,
      "geminiLiveOptions": "<unknown>",
      "appendBeforePrompt": "<string>",
      "routerLLmOptions": {
        "temperature": 123,
        "maxTokens": 123,
        "customModelId": "<string>",
        "serverUrl": "<string>",
        "apiKey": "<string>"
      },
      "defaultLLmOptions": {
        "temperature": 123,
        "maxTokens": 123,
        "customModelId": "<string>",
        "serverUrl": "<string>",
        "apiKey": "<string>"
      },
      "backchannelOnChoosingNodes": true,
      "enableUiEngine": true,
      "fallbackModelIds": [],
      "silenceDetection": {
        "enabled": false,
        "timeoutSeconds": 60,
        "endCallAfterNPhrases": 1
      },
      "startCallPhrases": [
        "<string>"
      ],
      "fillerWordsOnToolUsage": true,
      "toolUsageBackchannelPhrasesByLanguage": {},
      "smartEndpointing": {
        "enabled": true,
        "waitSeconds": 123,
        "onPunctuationSeconds": 123,
        "onNoPunctuationSeconds": 123,
        "onNumberSeconds": 123
      },
      "stopSpeakPlan": {
        "minWords": 123
      },
      "callTimeoutSeconds": 123,
      "enableEndcallTool": true,
      "voiceSpecific": {
        "minCharacters": 123,
        "maxLengthWithoutPunctuation": 123
      },
      "enabledGlobalTools": [],
      "defaultToolOverrides": {}
    },
    "id": "<string>",
    "enableFallback": true,
    "fallbackSettings": {
      "creditThreshold": 123
    },
    "marketplace": {
      "enabled": true,
      "priceUSD": 123,
      "creatorDisplayName": "<string>",
      "shortDescription": "<string>",
      "documentation": "<string>",
      "toolsDocumentation": [
        {
          "name": "<string>",
          "description": "<string>",
          "codeUrl": "<string>",
          "docsUrl": "<string>",
          "setupInstructions": "<string>"
        }
      ],
      "tags": [
        "<string>"
      ],
      "screenshots": [
        "<string>"
      ],
      "demoUrl": "<string>",
      "videoUrl": "<string>",
      "version": "<string>",
      "changelog": "<string>",
      "supportEmail": "<string>",
      "listedAt": 123,
      "updatedAt": 123,
      "allowCanvasPreview": true,
      "allowTryAgent": true,
      "likeCount": 0,
      "downloadCount": 0
    },
    "disableRating": true,
    "chatEndMessage": "<string>",
    "aiIntroductionMessage": "<string>",
    "enableAIIntroductionMessage": true,
    "deployed": true,
    "captureIGStories": true,
    "gdprCompliance": true,
    "disableFileUpload": true,
    "privacyDisclaimer": {
      "enabled": true,
      "text": "<string>",
      "privacyPolicyUrl": "<string>",
      "acceptButtonLabel": "<string>",
      "privacyPolicyButtonLabel": "<string>"
    },
    "leadCollectionRules": {
      "enabled": true,
      "rules": [
        {
          "variables": [
            "<string>"
          ],
          "description": "<string>"
        }
      ]
    },
    "emailConfig": {
      "enabled": true,
      "assignedEmails": [
        {
          "connectionId": "<string>",
          "email": "<string>",
          "replyDelay": 0,
          "replyDelayMinutes": 0,
          "whenToReply": "always",
          "replyRule": "",
          "humanNotifyRule": "",
          "notifyWorkspaceOwners": true,
          "humanTakeoverEnabled": false,
          "humanTakeoverTimeoutMinutes": 0,
          "replyLength": "auto",
          "replyTone": "professional"
        }
      ]
    },
    "autoTest": {
      "enabled": true,
      "triggerOnEdit": true,
      "maxTurns": 123,
      "naturalEnd": true,
      "testScenario": "<string>",
      "enabledToolIds": [
        "<string>"
      ],
      "enableKB": true
    },
    "langsmithConfig": {
      "enabled": true,
      "apiKey": "<string>",
      "projectName": "<string>",
      "endpoint": "<string>"
    },
    "funnelConfig": {
      "enabled": false,
      "steps": [],
      "notificationRules": [],
      "maxScore": 100,
      "evaluateOnUserMessage": true,
      "evaluateOnAIMessage": true
    }
  }
}

Usage

The Update Agent endpoint allows you to update an existing agent’s configuration. The API uses deep merging, so you only need to provide the fields you want to update.

Important: Agent instructions are stored in the nodes array, not at the top level. To update your agent’s prompt/instructions, you must update the nodes[0].instructions field where the node has id: "__start__".

Updating Agent Instructions

Agent instructions are stored within the nodes array. Each agent has a start node with id: "__start__" that contains the main instructions.

Example: Update Instructions Only

{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Your new instructions here. Be a helpful assistant that answers questions about our products."
      }
    ]
  }
}

Example: Update Instructions and LLM Model

{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "You are a friendly customer support agent. Help users with their questions.",
        "llmConfig": {
          "modelId": "gpt-4o",
          "temperature": 0.7,
          "maxTokens": 2048
        }
      }
    ]
  }
}

Example: Update Agent Metadata and Instructions

{
  "id": "your_agent_id",
  "agent": {
    "title": "My Updated Agent",
    "description": "A helpful customer support assistant",
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Greet users warmly and help them with their inquiries."
      }
    ]
  }
}

Node Structure

Each node in the nodes array can have the following properties:

Property	Type	Description
id	string	Required. The node identifier. Use "__start__" for the main start node.
instructions	string	The prompt/instructions for the LLM at this node.
name	string	Display name for the node.
description	string	Description of what the node does.
llmConfig	object	LLM configuration including modelId, temperature, and maxTokens.
toolsIds	array	Array of tool IDs assigned to this node.
kb	object	Knowledge base settings with enabled (boolean) and maxChunks (number).

Using Variables and Tools in Instructions

You can reference variables and tools in your instructions using the following syntax:

• Variables: {{var:variable_id}}
• Tools: {{tool:tool_id}}

{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Greet the user and store their name in {{var:user_name_variable_id}}. When they ask for help, use the {{tool:search_tool_id}} tool to find relevant information."
      }
    ]
  }
}

Updating Custom Theme & Color Palette

You can customize your agent’s appearance by setting a custom color palette. This requires setting both the theme field and the customThemeJSONString field.

Example: Custom Dark Theme

{
  "agent": {
    "theme": "custom-dark",
    "customThemeJSONString": "{\"themeType\":\"dark\",\"primary\":\"#8A2BE2\",\"nineColorPallet\":[[270,15,10],[270,15,15],[270,10,25],[270,10,50],[270,15,85],[270,25,95],[270,80,55],[270,85,65],[270,90,75],[270,95,85]],\"autogenTheme\":false}"
  }
}

Example: Custom Light Theme

{
  "agent": {
    "theme": "custom-light",
    "customThemeJSONString": "{\"themeType\":\"light\",\"primary\":\"#0096c7\",\"nineColorPallet\":[[199,100,39],[45,100,50],[0,0,10],[142,76,45],[217,100,61],[25,89,56],[280,83,57],[160,100,40],[187,85,55],[142,100,30]],\"autogenTheme\":false}"
  }
}

Custom Theme JSON Structure

The customThemeJSONString is a stringified JSON object with the following properties:

Property	Type	Description
themeType	"light" or "dark"	Base theme mode. Must match the theme field suffix.
primary	string	Primary accent color in hex format (e.g., "#8A2BE2").
nineColorPallet	array	Array of 10 HSL color values, each as [Hue, Saturation, Lightness].
autogenTheme	boolean	If true, auto-generates the palette from the primary color.

HSL Color Format

Each color in nineColorPallet is an array of 3 numbers:

• Hue: 0-360 (position on the color wheel)
• Saturation: 0-100 (color intensity percentage)
• Lightness: 0-100 (brightness percentage)

Important: When updating the custom theme, ensure that:

1. The theme field matches the themeType in the JSON string (e.g., "custom-dark" with "themeType": "dark")
2. The nineColorPallet array contains exactly 10 HSL color values
3. The customThemeJSONString is a properly escaped JSON string

Auto-Generate Palette

If you only want to set a primary color and have the palette auto-generated:

{
  "agent": {
    "theme": "custom-light",
    "customThemeJSONString": "{\"themeType\":\"light\",\"primary\":\"#6366f1\",\"autogenTheme\":true}"
  }
}

Example Response

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "ID": "your_agent_id",
    "title": "My Updated Agent",
    "description": "A helpful customer support assistant",
    "nodes": [
      {
        "id": "__start__",
        "name": "Start",
        "instructions": "Greet users warmly and help them with their inquiries.",
        "llmConfig": {
          "modelId": "gpt-4o",
          "temperature": 0.7,
          "maxTokens": 2048
        }
      }
    ]
  }
}

Legacy Fields (Deprecated)

The following top-level fields are legacy fields and should not be used for new integrations. They are only used during migration from older agent formats:

• vg_systemPrompt
• vg_initPrompt
• vg_prompt
• vg_initMessages
• instructions (at the top level)

Always use the nodes array to update agent instructions.

Notes

• The API uses deep merging, so only the fields you specify will be updated
• When updating nodes, the merge is performed by matching the id field
• You only need to provide the node properties you want to change; other properties will be preserved
• The lastModified timestamp is automatically updated
• If the agent doesn’t exist, a 404 error will be returned
• You must be the owner of the agent to update it

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · required

Body

application/json

agent · any

Response

200

application/json

Successful response

success · boolean · required

message · string · required

data · object · required

Show child attributes