sf-agent-api-variables

Agent API Variables

Use This Skill When

• Passing context variables ($Context.*) or custom variables in a start-session or send-message call.
• Deciding which variables can be set at start vs edited mid-conversation.
• Configuring variable API accessibility in Agentforce Builder or via Metadata API (ConversationVariable, ConversationContextVariable).

Concept

You can pass two kinds of variables so the agent can use them on subsequent turns:

• Context variables — prefixed $Context. (for example $Context.EndUserLanguage). Predefined session context.
• Custom variables — your own named values (for example team_descriptor, troubleshootingSteps).

Quick Start

Add a variables array to the start-session body (or a send-message body for editable variables):

{
  "externalSessionKey": "{RANDOM_UUID}",
  "instanceConfig": { "endpoint": "https://{MY_DOMAIN_URL}" },
  "streamingCapabilities": { "chunkTypes": ["Text"] },
  "bypassUser": true,
  "variables": [
    { "name": "$Context.EndUserLanguage", "type": "Text", "value": "en_US" },
    { "name": "team_descriptor", "type": "Text", "value": "The Greatest Team" },
    { "name": "troubleshootingSteps", "type": "Text", "value": "Complete this list of troubleshooting steps: 1. Confirm username/password. 2. ..." }
  ]
}

Each variable has name, type, and value.

Editability Rules

• Many variables are read-only and can only be set during the start session call.
• Context variables ($Context prefix) are not editable after the session starts — except $Context.EndUserLanguage.
• Only editable variables can be modified during a send-message call.
• When referencing variables derived from custom fields, omit the `__c` suffix. Example: Conversation_Key__c → $Context.Conversation_Key.

Variable Types

Text, Number, Boolean, Object, Date, DateTime, Currency, Id.

Configuring Accessibility

Agentforce Builder

When creating an agent variable, check Allow value to be set by API so the API can populate it.

Metadata API

Configure via ConversationVariable (in BotVersion/BotTemplate) and ConversationContextVariable (in Bot/BotTemplate).

Key fields:

Do not change includeInPrompt for the default Id, EndUserId, and EndUserLanguage variables — doing so can block the agent from key session data.

Guardrails

• To set a variable via API it must be external visibility (ConversationVariable) and "Allow value to be set by API" enabled.
• Strip __c from custom-field-derived names, and use the $Context. prefix for context variables.
• Don't try to mutate read-only/context variables after start (except $Context.EndUserLanguage) — the change is ignored.
• Treat variable values as untrusted input downstream; validate before using in SOQL, HTML, or callouts.
• Keep prompt-injected variables (includeInPrompt: true) minimal and non-sensitive.

Deliverables

• A variable contract: name, type, context-vs-custom, set-at-start-vs-editable, and API accessibility.
• Metadata definitions (ConversationVariable / ConversationContextVariable) for any API-settable variables.
• A validation plan for how variable values are consumed downstream.

Additional Resources

• Where variables attach in the request flow: sf-agent-api-session-lifecycle, sf-agent-api-messaging
• Full metadata field list: reference.md
• Official docs: Send Agent Variables with the Agent API