关于 Script 视图和 Canvas 视图
以下 12 个模式使用 Agent Script 以 Script 视图的形式编写，方便你直接复制粘贴到自己的 Agent 中复用。这些模式同样适用于 Canvas 视图。
通用指导原则
在使用 Agent Script 构建 Agent 时，请牢记以下核心原则：
从简单的推理指令开始。从最少必要的指令开始，随着预览不同用例逐步添加，每次更改之间测试回归
使用好的命名和描述。名称要具体、独特且与 Agent 的任务明确相关。使用最终用户容易理解的通俗语言，全程保持一致
策略性地添加确定性。在自然语言指令和确定性逻辑表达式之间取得平衡，为业务工作流添加逻辑以提高可预测性
在推理指令中直接引用资源。使用 @ 提及引用子代理、动作和变量，给 LLM 明确的指导
模式 1：动作链和排序（Action Chaining & Sequencing）
以确定的顺序运行多个动作，创建可靠的多步骤工作流。
指令中的顺序动作
在推理指令中逐个调用动作，两个动作都在提示发送给 LLM 之前确定性地运行：
`reasoning:
instructions: ->
# 第一个动作
run @actions.lookup_current_order
with member_email=@variables.member_email
set @variables.order_summary=@outputs.order_summary
# 下一个动作
run @actions.lookup_current_user
with member_email=@variables.member_email
set @variables.user_profile=@outputs.profile
| Show the user their order summary and welcome them by name.`
注意：在指令中运行动作时，必须手动设置变量的输入和输出，因为动作在推理之前运行。
### 运行动作后转换
运行动作后自动转换到另一个子代理，适用于验证后路由的场景：
`reasoning:
actions:
validate_user_ready: @actions.validate_user_ready
with user_id=@variables.user_id
set @variables.is_ready=@outputs.ready
transition to @subagent.analyze_issue`
条件链
基于前一个动作的结果有条件地链式执行后续动作：
`run @actions.check_eligibility
with user_id=@variables.user_id
set @variables.is_eligible=@outputs.eligible
if @variables.is_eligible == True:
run @actions.fetch_offer_details
set @variables.offer=@outputs.offer
| Present the offer: {!@variables.offer}
else:
| Explain that the user is not eligible for this offer.`
## 模式 2：Agent Router 策略
`start_agent` 块（Agent Router）控制 Agent 的入口点和路由逻辑。每次用户发言都从此块开始。
`start_agent agent_router:
description: "Welcome the user and determine the appropriate subagent"
reasoning:
instructions: ->
| Select the best tool based on conversation history and user's intent.
actions:
go_to_orders: @utils.transition to @subagent.Order_Management
description: "Handles order lookup, refunds, order updates, and summarizes status, order date, current location, delivery address, items, and driver name."
go_to_returns: @utils.transition to @subagent.Returns
description: "Processes return requests for orders within the 60-day return window."`
关键技巧：
限制子代理数量 —— 从必要的开始，逐步添加。子代理越少，路由决策越清晰
使用 goto 前缀 —— 让 Agent 明白这是导航到其他子代理的动作
编写详细的描述 —— 尤其是有相似子代理时，描述要详细且唯一
基于上下文隐藏子代理 —— 使用 available when 控制可见性
模式 3：使用条件语句（Conditionals）
使用条件语句确定性控制 Agent 行为。条件在提示发送给 LLM 之前评估，不依赖 LLM 解释。
条件指令
if @variables.loyalty_tier == "Gold": | Thank the customer for being a Gold member. if @variables.loyalty_tier == "Platinum VIP": | Thank the customer for being a Platinum VIP member.
只有匹配条件的指令会包含在发送给 LLM 的提示中。
### 条件动作
`if @variables.order_summary == "":
run @actions.lookup_current_order
with member_email=@variables.member_email
set @variables.order_summary = @outputs.order_summary`
条件转换
if @variables.loyalty_tier == "Platinum VIP": transition to @subagent.vip_support
### If/Else 逻辑和多条件
`if @variables.order_summary.days_since_order 关键技巧：
- 初始化变量 —— 给变量默认值（如 "" 或 False）以便条件检查正确工作
- 使用 is None 检查空值 —— 与检查空字符串（== ""）不同
- 用括号控制求值顺序 —— 明确分组复合条件
## 模式 4：在推理前获取数据（Fetch Data Before Reasoning）
在推理指令的顶部放置动作调用，在构建提示之前获取数据，确保 LLM 能访问最新、准确的信息。
### 基本模式（4 步）
`# 1. 检查数据是否已获取
if @variables.order_summary == "":
# 2. 如果未获取，运行查找动作
run @actions.lookup_current_order
with member_email=@variables.member_email
# 3. 将结果存储在变量中
set @variables.order_summary=@outputs.order_summary
# 4. 在提示中引用变量
| Refer to the user by name {!@variables.member_name}.
Show them their current order summary: {!@variables.order_summary}.`
模式 5：使用过滤器执行业务规则（Filtering）
使用 available when 控制 LLM 可以访问哪些子代理或动作。如果条件不满足，LLM 无法使用该资源。
过滤子代理
actions: go_to_info: @utils.transition to @subagent.General_Info description: "Gives general information about products." go_to_order: @utils.transition to @subagent.Order_Management description: "Handles order lookup, refunds, order updates." available when @variables.verified == True go_to_escalation: @utils.transition to @subagent.Escalation available when @variables.verified == True and @variables.is_business_hours == True
### 过滤动作
`actions:
create_return: @actions.create_return
available when @variables.order_return_eligible == True and @variables.order_id != None`
注意：LLM 可以调用任何可用的推理动作，即使你没有明确告诉它。不要仅依赖提示工程来保护敏感功能。
模式 6：强制要求的子代理工作流（Required Subagent Workflow）
在指令顶部使用条件转换，强制用户通过必需的步骤。与 available when 过滤不同，这些转换立即执行并保证路由行为。
三种执行方式对比
方式使用场景
available when控制哪些推理动作可用；LLM 在可用选项中自行选择
条件转换要求用户必须完成某步骤；没有 LLM 选择权
多轮步骤变量通过子代理强制执行逐步排序，每个子代理处理多个对话轮次
所有子代理的强制流程（在 Agent Router 中）
start_agent agent_router: reasoning: instructions: -> if @variables.verified == False: transition to @subagent.Identity | Select the best tool based on conversation history and user's intent.
未验证用户被立即路由到身份验证子代理 —— 不进行子代理分类，不发送 LLM 提示。
### 单个子代理的强制前置条件
`subagent Order_Management:
reasoning:
instructions: ->
if @variables.order_id is None:
transition to @subagent.Order_Lookup
| Help the user with their order {!@variables.order_id}.`
模式 7：多轮对话中的强制工作流（Multi-Turn Step Variables）
使用步骤变量控制 Agent Router 选择哪个子代理。在每个子代理中，让 Agent 评估客户的回答并设置下一步的步骤变量。
start_agent agent_router: reasoning: instructions: -> if @variables.currentInterviewStep == "Permission": transition to @subagent.permission if @variables.currentInterviewStep == "Eligibility": transition to @subagent.eligibility if @variables.currentInterviewStep == "End": transition to @subagent.end_interview
在子代理中，使用 `@utils.setVariables` 配合 `...`（省略号）让 LLM 通过推理设置变量值（槽位填充）。
## 模式 8：在推理指令中直接引用资源（Resource References）
使用 @ 提及和花括号语法直接在推理指令中引用子代理、动作和变量。
### 引用语法
- 子代理：`{!@subagents.<subagent_name>}`
- 动作：`{!@actions.<action_name>}`
- 变量：`{!@variables.<variable_name>}`
`| Refer to the user by preferred name {!@variables.preferred_name}.
Order Name: {!@variables.order_name}
Order Status: {!@variables.order_status}
| If the user wants information about a past order, ask for the Order ID
and use {!@actions.lookup_order}.
If the user seems upset, go to {!@actions.go_to_escalation}.`
模式 9：使用指令覆盖避免冲突（System Overrides）
默认情况下，所有子代理继承 Agent 级别的 system.instructions。在特定子代理中添加 system 块，可以仅为该子代理覆盖系统指令。
指令层级
子代理级 system 指令（最高优先级） —— 如果子代理有 system 块，使用这些指令
Agent 级 system 指令（回退） —— 如果子代理没有 system 块，使用全局指令
创建多角色
技术支持角色："Use precise technical terminology, provide step-by-step troubleshooting, be patient and thorough."
创意模式角色："Think outside the box, suggest unconventional ideas, use enthusiastic language, be imaginative and supportive."
模式 10：子代理转换（Subagent Transitions）
转换是单向的 —— 当发生转换时，Agentforce 丢弃当前子代理的任何提示，转而处理新的子代理。
推理转换（LLM 选择）
actions: go_to_order: @utils.transition to @subagent.Order_Management description: "Handles order lookup, refunds, order updates." go_to_identity: @utils.transition to @subagent.Identity available when @variables.verified == False
### 确定性转换（无需 LLM 选择，不使用 @utils. 前缀）
`# 条件转换
if @variables.loyalty_tier == "Platinum VIP":
transition to @subagent.vip_support
# 动作后链接转换
validate_user_ready: @actions.validate_user_ready
with user_id=@variables.user_id
transition to @subagent.analyze_issue`
模式 11：有效使用变量（Using Variables）
变量在子代理和对话轮次之间存储 Agent 的当前状态信息。策略性地使用它们来跟踪重要信息，但不要存储每个数据片段从而过度限制 Agent。
初始化变量
`# 使用空字符串存储稍后获取的数据
order_summary: mutable string = ""
使用 False 作为初始标志
verified: mutable boolean = False
不初始化需要必须提供的值
member_email: mutable string`
### 让 LLM 设置变量（槽位填充）
`actions:
capture_user_info: @utils.setVariables
with first_name = ...
with last_name = ...
description: "Set the user's name as variables"`
... 表示 LLM 应使用推理来设置变量的值。
模式 12：使用列表变量（List Variables）
列表变量（又称集合变量）让 Agent 能够存储和遍历一组值。列表索引从 0 开始。
声明列表
CandidateList: mutable list[object] = [] description: "List of contacts returned from an action" CompetencyQuestions: mutable list[string] = ["Tell me about a time...", "Tell me about one of your favorite shifts."]
### 使用列表项
`# 引用特定项
| Ask the candidate this question: {!@variables.CompetencyQuestions[0]}
# 使用变量作为动态索引
| Ask this question: {!@variables.questions[@variables.current_question]}
# 在条件表达式中
if @variables.areAnswersCorrect[2] == "False":
transition to @topic.end_interview
# 获取列表长度
| This is question {!@variables.question_index + 1} of {!len(@variables.questions)}.`
遍历列表
Agent Script 没有 for 循环，通过在每个轮次后递增索引变量来遍历：
if @variables.is_GetQuestions_run == False: run @actions.Get_Questions set @variables.questions = @outputs.AllScreeningQuestions set @variables.question_index = 0 set @variables.is_GetQuestions_run = True | Ask this question: {!@variables.questions[@variables.question_index]}
```
以上 12 个模式涵盖了 Agent Script 开发中最常见的场景。每个模式都提供了可复用的代码模板，帮助你构建更可靠、更高效的 Agentforce Agent。
发布来源：https://www.salesforcecrm.cn/article/agentforce/agent-script-common-patterns.html
