什么是 Agent Script？
Agent Script 是用于在 Agentforce Builder 中构建 Agent 的语言。它将自然语言指令处理对话任务的灵活性与程序化表达式处理业务规则的可靠性相结合。在 Script 中，你可以使用表达式定义 if/else 条件、转换和其他逻辑；设置、修改和比较变量；以及选择子代理（subagent）和动作（action）。你可以构建可预测、上下文感知的 Agent 工作流，而不是仅仅依赖 LLM 的解释。
注意：从 2026 年 4 月开始，Agent 的 topics 现已更名为 subagents（子代理），功能上没有变化。
编写 Agent Script 的多种方式
Agentforce Builder 提供了多种编写 Agent Script 的方式：
与 Agentforce 对话 —— 用自然语言解释你想让 Agent 做什么（例如"If the order total is over $100, then offer free shipping"），Agentforce 会自动将请求转换为子代理、动作、指令和表达式
Canvas 视图 —— Agent Script 被总结为易于理解的块，可以展开查看底层脚本。输入
/添加常见模式的表达式，输入@添加资源Script 视图（高级） —— 直接编写和编辑脚本，支持语法高亮、自动补全和验证
Agentforce DX（VS Code） —— 生成或获取脚本文件到本地 Salesforce DX 项目，在 VS Code 中使用完整的扩展支持进行开发
Agent Script 能做什么？
Agent Script 保留了来自自然语言提示的对话技能和复杂推理能力，同时增加了程序化指令的确定性。在 Agent Script 中，你可以定义：
推理指令（Reasoning Instructions） —— 定义 LLM 可以自由做出推理决策的特定领域，以及 Agent 必须确定性执行的特定领域
变量（Variables） —— 可靠地存储有关 Agent 当前状态的信息，而不依赖 LLM 的上下文记忆
条件表达式（Conditional Expressions） —— 根据变量值确定 Agent 的执行路径或 LLM 的表述方式
子代理转换（Subagent Transitions） —— 确定性地转换到新子代理，或将子代理转换作为工具暴露给 LLM，让 LLM 决定何时切换
动作控制（Action Control） —— 根据变量值确定性地指定要运行的动作
Agent Script 示例
这是一个简单的 Agent Script 示例，展示了条件逻辑（->）与 LLM 提示（|）的结合使用：
`system:
instructions: "You are a friendly and empathetic agent that helps customers with their questions."
messages:
error: "Sorry, something went wrong."
welcome: "Hello! How are you feeling today?"
config:
agent_name: "HelloWorldBot"
default_agent_user: "hello@world.com"
variables:
isPremiumUser: mutable boolean = False
description: "Indicates whether the user is a premium user."
start_agent hello_world:
description: "Respond to the user."
reasoning:
instructions: ->
if @variables.isPremiumUser:
| ask the user if they want to redeem their Premium points
else:
| ask the user if they want to upgrade to Premium service`
这个示例展示了 Agent Script 的核心优势：确定性逻辑（`->` 后）与 LLM 推理（`|` 后）可以在同一个工作流中共存，既保证了可预测的执行，又保留了 LLM 处理自然对话的能力。
## 语言特性
### 编译型语言
Agent Script 是一种编译型语言。当你保存 Agent 的一个版本时，脚本会编译为推理引擎使用的底层元数据。
### 确定性 + 推理的混合模式
Agent Script 在单个工作流中结合了确定性逻辑和 LLM 推理：
- 逻辑指令（`->`）—— 每次确定性地运行。用于业务规则、运行动作、设置变量和条件分支
- 提示指令（`|`）—— 发送给 LLM 的自然语言。LLM 解释这些指令并决定如何回应客户
### 声明式与过程式的结合
- 声明式 —— 直接声明你想要什么，无需担心逐步的详细流程。基本的 Agent Script 块类似于声明式语言
- 过程式 —— 指定按特定顺序执行命令。推理指令中的逻辑类似于过程式语言
### 面向属性（Property-Based）
Agent Script 由一组属性组成，每个属性以 `key: value` 的形式呈现。顶层属性称为"块"（blocks），例如 config 块：
`config:
developer_name: "Demo_Agent_1"
default_agent_user: "digitalagent.demo@salesforce.com"
agent_label: "Demo Agent"
description: "This is my demo agent"`
缩进和格式化
Agent Script 对空白敏感，类似于 Python 或 YAML。缩进用于指示结构和属性之间的关系。必须选择一种缩进方法（至少 2 个空格或 1 个 Tab）并在整个脚本中保持一致，混合使用会导致解析错误。
箭头符号（
->）—— 用于逻辑指令，后跟缩进的指令管道符号（
|）—— 用于多行字符串和从逻辑切换到提示模式
访问资源
使用 @ 符号访问资源：
@actions.<action_name>—— 引用动作@subagent.<subagent_name>—— 引用子代理@variables.<variable_name>—— 引用变量@outputs.<output_name>—— 引用动作输出
使用 run 命令执行动作，with 提供输入，set 存储输出。在提示文本中引用变量需使用 {!@variables.<variable_name>} 语法。
表达式和注释
Agent Script 使用熟悉的流程控制语法（if/else）、数学表达式（+、-）、比较表达式（==、!=、>、<）以及空值检查（is None、is not None）。
使用 # 符号添加注释，脚本会忽略 # 之后的任何内容。
Agent Script 块
脚本由多个块组成，每个块包含一组属性。以下是各块类型的高层理解。
System 块
包含 Agent 的通用指令和消息提示。必需的 welcome 和 error 消息支持多行（使用 |）和链接变量（{!@variables.xxx}）来动态注入内容。
Config 块
包含定义 Agent 的配置参数：developer_name（唯一 API 名称）、default_agent_user、agent_label、description、enable_enhanced_event_logs 等。
Variables 块
包含 Agent 和脚本可以使用的全局变量列表。使用 variable_name: mutable type = default_value 定义，通过 @variables.<variable_name> 引用。
Language 块
定义 Agent 支持的语言，设置 default_locale 和 additional_locales。
Connection 块
描述 Agent 如何与外部连接（如 Enhanced Chat）交互，包括升级消息、出站路由配置等。与 @utils.escalate 命令配合使用。
Start Agent 块（Agent Router）
使用 start_agent 前缀代替 subagent。每次客户发言时，Agent 从此块开始执行。通常用于子代理分类、过滤和路由，可包含条件转换（如 available when @variables.verified == True）。
Subagent 块
指定子代理的指令、逻辑和动作。核心属性包括：
name —— snake_case 命名的子代理标识
description —— 帮助 Agent 根据用户意图确定何时使用此子代理
system.instructions（可选）—— 覆盖系统级指令，避免冲突指令或更改语气
reasoning —— 包含发送给推理引擎的
instructions（可组合逻辑和提示）和actions（可用的工具列表）actions —— 定义从此子代理可用的 Agent 动作，包含描述、输入、输出和目标位置
Connected_Subagent 块（Beta）
定义到 Salesforce 组织中另一个 Agentforce Agent 的连接。关键属性包括 target（外部 Agent 的 URI）、inputs（传递给连接子代理的值）、可选的 label、description 和 loading_text。使用 @connected_subagent.Name 作为推理动作。
在 Agent Script 中配置模型
默认情况下，Agentforce 使用在设置中选择的模型。你可以使用 model_config 为特定 Agent 或其子代理覆盖组织的默认模型。
model_config: model: "model://sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet"
### 模型配置层级
- Agent 级别 —— 在顶层使用 `model_config` 覆盖组织默认模型
- Subagent 级别 —— 在子代理内使用 `model_config` 覆盖 Agent 级别模型
- Agent Router 级别 —— 在 `start_agent` 中使用 `model_config`
优先级：子代理特定模型 > Agent 特定模型 > 组织默认模型。
### EinsteinHyperClassifier 模型
由 Salesforce 开发的专用于子代理分类的模型。优势：分类速度显著更快、对特殊分类约束和否定指令的准确率更高。限制：不能使用 `before_reasoning` 或 `after_reasoning`，只能使用 `@utils.transition` 工具。
## Agent Script 控制流程
理解执行顺序和控制流程有助于设计更好的 Agent。Agentforce 有三个主要执行路径：
### 1. 首次请求
所有请求（包括首次请求）都从 `start_agent` 块（Agent Router）开始。通常用于设置变量的初始值并执行子代理分类，让 LLM 根据当前上下文选择子代理。
### 2. 处理子代理
Agentforce 使用子代理的文本指令、变量、if/else 条件和其他程序化指令来创建 LLM 提示词。推理指令按从上到下的顺序依次处理。LLM 只在接收已解析提示词后才开始推理，而不是在 Agentforce 解析过程中。
如果推理指令中包含转换命令，Agentforce 会立即转换到指定子代理，丢弃任何现有的已解析提示词。最终提示词只包含从第二个子代理解析的指令。
### 示例：Agentforce 如何创建提示词
假设一个 `Order_Management` 子代理，订单 ID 为 1234，当前交付日期为 2026 年 2 月 10 日，包裹已延迟。Agentforce 逐行处理：递增变量、运行动作、评估条件并拼接提示文本。最终发送给 LLM 的提示词可能为：
`Tell the user that the expected delivery date for order number 1234 is February 10, 2026.
Apologize to the customer for the delay in receiving their order.`
3. 子代理之间的转换
转换（使用 @utils.transition to）是单向的，控制不会返回到之前的子代理。Agentforce 丢弃前一个子代理的任何提示指令，然后从头到尾读取第二个子代理。第二个子代理完成后，Agentforce 等待下一次客户发言，然后返回到 start_agent。
管理、下载和示例
配置和部署
你可以从 Salesforce 组织或通过命令行使用 Agentforce DX 来配置、部署和测试 Agent。有多种测试方法可供选择，发布后务必再次测试。
下载 Agent Script 文档
可以将 Agent Script 文档下载为 Markdown 文件，用作编码 Agent 的关联上下文。文档包每周四晚上（PST）更新，包含：语言概述、脚本块、模型配置、控制流程、参考语法、模式和完整示例。
Agent Script 示例
客户支持 —— 验证身份并提供订单信息
面试 Agent —— 基于步骤变量的面试流程控制
术语关联 —— 处理不断演变的术语而不更新信息源
Agent Script Recipes 和开发技能
访问 https://developer.salesforce.com/sample-apps/agent-script-recipes Agent Script Recipes 获取更多交互式示例。使用 https://github.com/forcedotcom/afv-library/tree/main/skills/developing-agentforce Agentforce Development Skill 来构建、修改、调试和部署 Agent。
感谢阅读本指南。Agent Script 为你提供了两全其美的能力 —— LLM 推理的灵活性加上确定性程序化控制的可预测性。
发布来源：https://www.salesforcecrm.cn/article/agentforce/agent-script-guide.html
