使い方
- インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
- 必要なツール、認証情報、対応環境を原文で確認します。
- 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-agent-api-variables開始前の確認
- 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
- スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文
見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。
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):
json
{
"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 (
$Contextprefix) 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
externalvisibility (ConversationVariable) and "Allow value to be set by API" enabled. - Strip
__cfrom 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
