Agent Script 通用模式指南

Agent Script 通用模式

本章提供使用 Agent Script 构建 Agent 的12 个通用模式。每个模式聚焦于一种特定技术，帮助你让 Agent 更可靠、更高效。所有模式均以 Script 视图格式编写，可直接复制粘贴到你的 Agent 中重用，同时也适用于 Canvas 视图。

12 个可用模式一览

模式	描述
Action Chaining & Sequencing	以保证的顺序运行多个动作
Agent Router Strategies	在 start_agent 块中设置高效的子代理路由
Using Conditionals	使用 if/else 逻辑控制指令、动作和跳转
Context Engineering	应用上下文工程策略优化 Agent
Fetch Data Before Reasoning	在 LLM 开始推理之前运行数据检索动作
Filtering with Available When	控制子代理和动作对推理引擎的可见性
Required Subagent Workflow	保证用户通过必要步骤后才能继续
Multi-Turn Required Workflows	通过多轮对话强制执行子代理排序
Resource References	在推理指令中直接引用变量和动作
System Overrides	覆盖全局系统指令以按子代理改变行为
Subagent Transitions	使用 @utils.transition to 在子代理之间移动
Using Variables Effectively	跨子代理存储和高效使用状态
Using List Variables	使用列表（集合）变量存储和迭代多个值

通用指导原则

使用 Agent Script 构建 Agent 时，牢记以下原则：

1. 从简单的推理指令开始。以最少的必要指令开始让 Agent 按预期工作。预览不同用例的用户对话后按需增量添加指令，每次变更之间回归测试
2. 使用好的命名和描述。清晰的名字帮助 Agent 做出更好的决策。

• 好的名称和描述是具体、独特且与 Agent 任务明确相关的
• 审查 Agent 中其他子代理、动作和变量的名称和描述，确保它们独特且不重叠
• 使用最终用户可能使用的自然语言而非技术术语。这让 Agent 更容易将用户问题匹配到相关资源
• 始终使用一致的语言。当语言模糊时，Agent 可能不一致或不正确地应用指令。例如，不要将一个动作命名为"Get Client Info"而另一个命名为"Verify Customer"——在两个地方统一使用"customer"

3. 策略性添加确定性。在自然语言指令和确定性逻辑表达式之间取得平衡。为业务工作流添加逻辑来增加可预测行为，同时保留 LLM 处理对话灵活性的能力
4. 在推理指令中直接引用资源。使用 @ 提及子代理、动作和变量给 LLM 明确的指导。直接引用资源是给 LLM 的更强信号，增加 Agent 按预期使用资源的概率

模式一：动作链与顺序执行

以保证的顺序运行多个动作。动作链可以通过多种方式实现，取决于何时以及如何执行动作。

应用场景：获取用户订单后立即检查该订单的退货资格。动作顺序确保一个动作可以触发另一个，创建可靠的多步骤工作流，不依赖 LLM 记住多个步骤。

顺序动作 + 链式推理动作

指令中的顺序动作

在推理指令中逐个调用动作。两个动作都在 Prompt 发送给 LLM 之前确定性执行。也可以将一个动作的输出存入变量，作为另一个动作的输入或后续 Prompt 的一部分：

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.

注意：在指令中运行动作时，必须手动设置变量的输入和输出，因为动作在推理之前运行。

链式推理动作

定义一个后续动作，当 LLM 调用动作时自动运行。用 run 在推理动作定义中链接。每当 LLM 调用 my_action，Agent 自动在之后运行 other_action：

reasoning:
  actions:
    my_action: @actions.my_action
      with foo=@variables.Foo
      set @variables.status = @outputs.status
      run @actions.other_action
        set @variables.some_other_result=@outputs.data

动作+跳转 + 条件链 + 提示

运行动作后跳转

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

条件动作链

reasoning:
  instructions: ->
    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
        with user_id=@variables.user_id
        set @variables.offer=@outputs.offer
      | Present the offer: {!@variables.offer}
    else:
      | Explain that the user is not eligible for this offer.

提示：确定性流使用顺序指令；第二个动作需要第一个动作的输出时，用变量存储第一个动作的输出并作为第二个动作的输入。

模式二：Agent Router 策略

Agent Router（即 start_agent 块）是 Agent 的入口点，每次用户发言都从这里开始。它欢迎用户、分类意图、路由到合适的子代理，并根据用户状态控制哪些子代理可用。

基本结构 + 有效描述 + 子代理门控

基本 Router 结构

start_agent agent_router:
  description: "Welcome the user and determine the appropriate subagent"
  reasoning:
    instructions: ->
      | Select the best tool to call based on conversation history.
    actions:
      go_to_orders: @utils.transition to @subagent.Order_Management
        description: "Handles order lookup, refunds, and order updates."
      go_to_faq: @utils.transition to @subagent.General_FAQ
        description: "Handles FAQ lookup and common questions."
      go_to_escalation: @utils.transition to @subagent.Escalation
        description: "Escalate to a human representative."

有效描述是关键

描述要具体、独特、详细。好的描述帮助 Agent 选择最佳子代理：

go_to_order: @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."

子代理门控 + 确定性路由 + 提示

子代理门控（Subagent Gating）

使用 available when 控制子代理可见性。例如未验证用户只能看到身份验证，已验证用户才能访问订单管理。

确定性路由

对于关键路由决策，使用条件跳转而非依赖 LLM 选择。在指令顶部放置条件跳转，确保在 LLM 推理之前强制执行路由。

提示：从核心子代理开始，逐步添加；使用 go_to_ 前缀命名跳转动作；编写详细且独特的描述；使用 available when 基于上下文隐藏子代理；使用条件逻辑保证路由在其他处理之前发生。如果想控制子代理路由方式不同，甚至可以定义另一个子代理作为 start_agent。

模式三：使用条件判断

使用条件判断确定性控制 Agent 行为。条件判断在 Prompt 到达 LLM 之前评估，不依赖 LLM 的解读。

条件指令 + 条件动作 + 条件跳转

条件指令

根据变量值定制 Prompt。只有满足条件的指令才会被包含在发给 LLM 的 Prompt 中：

reasoning:
  instructions: ->
    | Refer to the user by name {!@variables.member_name}.
    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.

条件动作

只在特定条件满足时运行动作，减少不必要的系统调用：

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

跳转立即发生，在 LLM 处理任何其他指令之前。

If/Else + 多条件组合 + 提示

If/Else 逻辑

if @variables.order_summary.days_since_order <= 60:
  set @variables.return_eligibility = True
  | Offer to process return using {!@actions.create_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.

# 使用括号控制求值顺序
available when @variables.customerType == "Valued" and @variables.QualificationEnabled == True and (@variables.HasSalesInterest == True or @variables.WantsMeeting == True) and @variables.QualificationFlowStep != "COMPLETE"

提示：给变量设置默认值（如 = "" 或 = False）确保条件检查正确工作；使用 @variables.value is None 检查变量未赋值——这与检查空字符串 == "" 不同，空字符串是有效赋值，而 is None 检查未赋值；使用括号 () 显式分组被求值的条件，例如 available when ... and (... or ...) and ...。

模式四：在推理前获取数据

将动作调用放在推理指令顶部，在 Prompt 构建之前获取数据。确保 LLM 生成响应时能访问到最新、准确的信息。推理指令内的动作在 Prompt 发给 LLM 之前执行。

应用场景：在对话开始前查询用户的当前订单，使 Agent 能用订单状态和个性化推荐来问候用户。

基本模式 + 获取并验证

四步模式

reasoning:
  instructions: ->
    # 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. 在 Prompt 中引用变量
    | Show them their current order summary: {!@variables.order_summary}.

获取并验证

if @variables.order_summary == "":
  run @actions.lookup_current_order
    with member_email=@variables.member_email
    set @variables.order_summary=@outputs.order_summary

| If user wants to make a return:
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.

提示：始终检查数据是否存在后再调用获取动作，避免不必要的动作执行。

模式五：使用过滤器执行业务规则

使用 available when 控制子代理或动作对 LLM 的可见性。当条件不满足时，完全隐藏子代理或动作，简化 LLM 的决策并执行业务规则。

典型场景：仅当订单在退货窗口内且已验证时才启用 create_return 动作。仅在工作时间对已验证客户启用 escalate 子代理。

过滤子代理 + 过滤动作 + 提示

过滤子代理

actions:
  go_to_general: @utils.transition to @subagent.General_Info
      description: "Gives general information."
  go_to_order: @utils.transition to @subagent.Order_Management
      description: "Handles order lookup."
      available when @variables.verified == True
  go_to_escalation: @utils.transition to @subagent.Escalation
      description: "Escalate to a human rep."
      available when @variables.verified == True and @variables.is_business_hours == True

所有用户可访问 General Info；已验证用户可被路由到 Order Management；升级需要验证且工作时间。

过滤动作

actions:
  create_return: @actions.create_return
    available when @variables.order_return_eligible == True and @variables.order_id != None

注意：LLM 可以调用任何可用的推理动作，即使你没有显式告诉它。不要仅依赖 Prompt 工程来保护业务敏感功能——使用 available when 作为第一道防线，防止客户通过自然语言操纵 Agent 使用未授权的功能。在不使用过滤时，客户可能说服 LLM 使用不被允许的功能，或 LLM 可能在长对话中因上下文漂移而做出推理错误。

提示：用过滤器保护业务敏感功能免受客户操纵；嵌套 and/or 条件时用括号明确求值顺序。

模式六：强制要求的子代理工作流

使用条件跳转保证用户在访问其他功能之前通过必要的步骤。与过滤（移除选项）不同，条件跳转立即强制执行路由行为。

选择正确的方法 + 示例 + 提示

方法	何时使用
available when 过滤	控制哪些推理动作可用；LLM 从中选择
条件跳转	要求用户完成某步骤；无 LLM 选择余地
多轮对话步骤变量	强制执行步骤排序，每个子代理处理多轮对话

关键区分：对于身份验证等关键流程，指令中的条件跳转比仅使用 available when 过滤更可靠。过滤只是限制选项，但不能强制执行工作流 —— Agent 可能专门选择不需要验证的选项来绕过验证。

示例：全部子代理 + 单个子代理 + 步骤变量

全局强制验证（在 Agent Router 顶部）

start_agent agent_router:
  reasoning:
    instructions: ->
      if @variables.verified == False:
        transition to @subagent.Identity
      | Select the best tool based on conversation history.
    actions:
      go_to_orders: @utils.transition to @subagent.Order_Management
        description: "Handles order lookup, refunds."

未验证用户立即路由到 Identity。验证完成后，变量已设置，流程正常继续。

单子代理前提条件

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}.

提示：将条件跳转放在指令顶部；使用 go_to_ 前缀命名；使用描述性名称。

模式七：多轮对话中的必需工作流

使用步骤变量（Step Variable）在多轮对话中强制执行子代理排序。Agent Router 根据步骤变量的值选择子代理；子代理内部由 Agent 评估客户回答并设置下一步的步骤变量值。

何时使用：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

子代理控制下一步

subagent permission:
  reasoning:
    instructions: ->
      | Confirm whether the candidate has the legal right to work.
        If eligible, call {!@actions.setCurrentInterviewStep}
        with currentInterviewStep set to "Eligibility".
        If NOT eligible, set currentInterviewStep to "End".
    actions:
      setCurrentInterviewStep: @utils.setVariables
        with currentInterviewStep = ...

提示：每个子代理只负责验证一个答案；使用清晰的步骤名（permission、eligibility、availability）；让子代理自行决定何时答案满意并推进。

模式八：在推理指令中直接引用资源

在推理指令的 Prompt 文本中直接引用子代理、动作和变量。使用 {!@} 语法给 LLM 明确的指导，增加 LLM 选择正确资源的概率。

引用语法 + 综合示例

三种引用语法

• 子代理：{!@subagents.<name>}
• 动作：{!@actions.<name>}
• 变量：{!@variables.<name>}

综合示例

reasoning:
  instructions: ->
    | Refer to the user by name {!@variables.member_name}.
      Show their current order summary: {!@variables.order_summary}
      If the user wants to make a return, confirm their order ID and
      call {!@actions.create_return}. If returns are not eligible
      ({!@variables.order_return_eligible} is False), explain why.
      If they need more help, go to {!@actions.go_to_escalation}.

条件中的引用

if @variables.loyalty_tier == "Gold":
  | Thank the customer for being a Gold member.
    Their current points balance is {!@variables.points_balance}.
if @variables.loyalty_tier == "Platinum VIP":
  | Welcome back, valued Platinum VIP member {!@variables.member_name}!

提示：当你有大量动作时，添加引用帮助 Agent 选择正确的一个。直接引用是给 LLM 的更强信号。

模式九：使用指令覆盖避免冲突

在特定子代理中覆盖系统级指令（UI 中称为 Agent 级指令），动态改变 Agent 的行为和角色。当 Agent 级系统指令与子代理级推理指令矛盾时，Agent 可能会卡住或行为异常 —— 系统覆盖通过显式替换来解决此问题。

应用场景：活动策划 Agent 通常避免建议酒精饮品，但在成人派对子代理中覆盖系统指令以允许鸡尾酒推荐。或在不同子代理间切换技术专家/创意头脑风暴的角色。

指令层级 + 多角色创建

指令层级（优先级从高到低）

1. 子代理级 system.instructions（最高优先级） — 子代理有 system 块时使用
2. Agent 级 system.instructions（回退） — 子代理无 system 块时使用全局指令

解决冲突示例

# Agent 级（全局）
system:
  instructions: "NEVER suggest alcoholic beverages for children's parties."

# 子代理覆盖
subagent baby_first_birthday:
  system:
    instructions: "You may suggest beverages including champagne for adult guests, while ensuring child-appropriate food."

创建多角色（技术专家 vs 创意模式）

subagent technical:
  system:
    instructions: "You are a technical support specialist. Use precise technical terminology, provide step-by-step troubleshooting, ask diagnostic questions."

subagent creative:
  system:
    instructions: "You are a creative brainstorming partner. Think outside the box, suggest unconventional ideas, use enthusiastic language."

模式十：子代理跳转

使用 @utils.transition to 将执行从一个子代理移动到另一个。跳转是单向的——发生时 Agentforce 丢弃当前子代理的所有 Prompt，处理新子代理。

推理跳转 vs 确定性跳转

推理跳转（LLM 选择）vs 确定性跳转（脚本确定）的关键区别：

类型	方式	语法	使用场景
推理动作跳转	LLM 选择	actions 中定义 @utils.transition to	Agent Router 路由
过滤跳转	LLM 选择（受限）	+ available when	按状态控制可见性
条件跳转	确定性	指令中 transition to（无 @utils. 前缀）	强制工作流
动作后跳转	确定性	动作定义中 + transition to	动作完成后自动路由

推理跳转（暴露为 LLM 工具）

actions:
  go_to_escalation: @utils.transition to @subagent.Escalation
    description: "Escalate if requested or needed."

确定性跳转（条件触发）

if @variables.loyalty_tier == "Platinum VIP":
  transition to @subagent.vip_support  # 无 @utils. 前缀！

提示：确定性跳转慎用，仅在需要保证路由时使用；置顶条件跳转以减少不必要的延迟；避免创建跳转循环（A→B 且 B→A 无限循环）。

模式十一：有效使用变量

变量跨子代理和对话轮次存储 Agent 当前状态。策略性使用变量来跟踪重要信息，但避免过度存储每一条数据。典型用途包括：存储值供条件判断复用、存储动作输出、available when 条件检查。

初始化 + 存储 + 共享 + Slot Filling

初始化变量

variables:
  order_summary: mutable string = ""    # 后续获取的文本
  verified: mutable boolean = False     # 初始为负的标志
  member_email: mutable string          # 必须提供的值，不初始化

好的变量描述

is_business_hours: mutable boolean = False
  description: "Whether it is business hours. Used to determine if escalation is available."
loyalty_tier: mutable string
  description: "The customer's loyalty tier (Standard, Gold, Platinum VIP). Used for personalized greetings."

子代理间共享信息

run @actions.Get_Current_Weather_Data
  with city=@variables.user_city
  set @variables.temperature = @outputs.temperature_celsius
# temperature 现在对所有子代理可用

Slot Filling（LLM 设置变量值）

使用 ... 指示 LLM 用推理来设置变量值。LLM 可以询问用户姓名，然后使用 capture_user_info 工具设置这些变量的值。这种模式称为 Slot Filling。对于简单工作流，LLM 可以仅凭动作的描述和名称自行判断调用哪个动作；在本示例中显式引用 {!@capture_user_info} 确保 LLM 存储用户信息：

注意：Slot-filling 可用于顶层动作输入（由 LLM 调用），但不适用于链式动作输入（链式动作是确定性运行的）。

提示：命名清晰（order_return_eligible 而非 flag1）；推理指令中运行动作时必须手动为输入输出设置变量；推理动作中使用变量作为动作输入要谨慎——指定太多输入变量可能导致 Agent 选择动作不一致，仅在必要时基于测试结果指定；需要用于条件表达式或另一个动作时必须存储动作输出。

actions:
  capture_user_info: @utils.setVariables
    with first_name = ...
    with last_name = ...
    description: "Set the user's name as variables"

模式十二：使用列表变量

列表变量（集合变量）允许 Agent 存储和迭代一组值。可存储任何支持的类型（字符串、布尔值、数字、对象）。使用 [index] 引用列表项，索引从 0 开始。

应用场景：面试问题列表、搜索结果、跟踪收集进度。需要逐项处理时配对索引变量。

声明、引用与迭代

声明列表

variables:
  CandidateList: mutable list[object] = []
      description: "List of contacts returned from an action"
  CompetencyQuestions: mutable list[string] = ["Tell me about a time you disagreed with a coworker.", "Tell me about one of your favorite shifts."]
      description: "List of competency questions"

引用列表项

# 直接索引：第一个问题
| Ask: {!@variables.CompetencyQuestions[0]}

# 用变量索引
| Ask: {!@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)}.

迭代列表（无 for 循环）

Agent Script 没有 for 循环。通过在每个对话轮次后递增索引变量来模拟迭代：

variables:
  questions: mutable list[object] = []
  question_index: mutable number = 0
  is_GetQuestions_run: mutable boolean = False

topic ask_questions:
  reasoning:
    instructions: ->
      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: {!@variables.questions[@variables.question_index]}

Agent 记录答案后递增 question_index。当索引到达列表长度时跳转到下一个子代理。

掌握这 12 个模式是成为 Agent Script 专家的关键。建议按照"理解模式 → 复制示例 → 修改适配 → 测试验证"的流程逐个实践。