| name | sf-agent-api-variables |
| description | Agent API context and custom variables — passing session context to an agent and configuring variable accessibility. Use when sending context variables ($Context.*) or custom variables through the Agent API, controlling editability across turns, or configuring ConversationVariable / ConversationContextVariable via Agentforce Builder or Metadata API. |
| disable-model-invocation | true |
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:
| Field | Purpose |
|---|
dataType | Text, Number, Boolean, Object, Date, DateTime, Currency, Id |
developerName | Unique name; starts with a letter, no spaces, no trailing underscore, no double underscores |
label | Human-readable label in the UI |
description | Used by the Agentforce planner service |
includeInPrompt | Whether the variable is included in the prompt sent to the model |
visibility | internal = set only by action output; external = also settable by API (ConversationVariable only) |
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
