Agent Script 通用模式指南

关于 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."

关键技巧：

• 限制子代理数量 —— 从必要的开始，逐步添加。子代理越少，路由决策越清晰
• 使用 go_to_ 前缀 —— 让 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 <= 60:
  set @variables.return_eligibility = True
  | Offer to process return.
else:
  | Politely explain the return period has expired.

if @variables.verified == True and @variables.is_business_hours == True:
  | You can escalate to a live representative if needed.

关键技巧：

• 初始化变量 —— 给变量默认值（如 "" 或 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 块，可以仅为该子代理覆盖系统指令。

指令层级

1. 子代理级 system 指令（最高优先级） —— 如果子代理有 system 块，使用这些指令
2. 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。