Skip to main content

Update prompt variables

POST 
/api/v1/llm/update-prompt-variables

Agent Profiles: merges prompt variables into the thread for late-binding. The variables are re-rendered into the active profile's prompt on the next turn. Returns the merged conversation settings.

Prompt-variable update masks​

Section ID: DOC-MA-conversations-api-updatePromptVariables#prompt-variable-update-masks

When you supply updateMask:

  • Masked keys are authoritative. A masked key whose value is null or absent clears that variable.
  • Unmasked keys are untouched. Variables not listed in the mask keep their current values, even if you include them in the payload.

Without updateMask:

  • Supplied keys overwrite or add.
  • Null or empty values clear the variable.
  • Keys you omit are not touched.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Configure a support conversation that stays predictable · Profile selection and prompt versions

Request​

Responses​

Prompt variables merged

Merge a destination variable into an existing conversation’s prompt variables.​

Section ID: DOC-MA-conversations-api-updatePromptVariables#example-conversations-updatePromptVariables-request

Request example

{
  "conversationKey": "example_123",
  "variables": {
    "destination": "Paris"
  }
}

Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-updatePromptVariables#example-cookbook-managed-agents-conversations-configuration-03-request

Request example

{
  "conversationKey": "support-chat-001",
  "variables": {
    "userName": "Jane",
    "planTier": "pro"
  }
}

Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-updatePromptVariables#example-cookbook-managed-agents-conversations-configuration-json-03-request

Request example

{
  "conversationKey": "support-chat-001",
  "variables": {
    "planTier": "enterprise"
  },
  "updateMask": "planTier"
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-MA-conversations-api-updatePromptVariables#example-conversations-updatePromptVariables-response

Response example

{
  "settings": {
    "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW",
    "maxLoops": 1,
    "maxParallelTools": 1,
    "mcpServers": [
      {
        "serverId": "example_123",
        "enabled": true,
        "priority": 1,
        "allowlistToolPatterns": [
          "example"
        ],
        "blocklistToolPatterns": [
          "example"
        ]
      }
    ],
    "toolPolicy": {
      "requireApprovalToolNamePatterns": [
        "example"
      ],
      "requireApprovalServerIds": [
        "example_123"
      ],
      "autoApproveToolNamePatterns": [
        "example"
      ],
      "autoApproveServerIds": [
        "example_123"
      ],
      "approvalMode": "APPROVAL_MODE_MIXED",
      "clientToolMode": "CLIENT_TOOL_MODE_MIXED",
      "approvalTimeoutMs": 1,
      "failOnApprovalTimeoutToolNamePatterns": [
        "example"
      ],
      "stableSortByCallIndexOnTie": true,
      "maxParallelToolCalls": 1,
      "maxToolCallsPerLoop": 1,
      "maxTotalToolCalls": 1,
      "retriableToolNamePatterns": [
        "example"
      ],
      "maxRetries": 1,
      "retryableErrorSubstrings": [
        "example"
      ],
      "nonRetryableErrorSubstrings": [
        "example"
      ],
      "clientToolTimeoutMs": 1,
      "failureMode": "FAILURE_MODE_CONTINUE"
    },
    "promptVariables": {
      "example": "value"
    }
  }
}

Document ID: DOC-MA-conversations-api-updatePromptVariables. Section identities and revisions.

SectionStable reference
Update prompt variablesDOC-MA-conversations-api-updatePromptVariables#overview
RequestDOC-MA-conversations-api-updatePromptVariables#request
ResponsesDOC-MA-conversations-api-updatePromptVariables#responses