Agent Script 开发指南

Agent Script 入门

Agent Script 是 Agentforce Builder 中构建 Agent 的语言。它结合了处理对话任务的自然语言灵活性和处理业务规则的程序化可靠性。通过 Agent Script，你可以构建可预测的、上下文感知的 Agent 工作流，而不是完全依赖 LLM 的解读。

要上手实践：创建一个 Agent，然后从视图切换器中选择 Script；或使用 Agentforce DX 在 VS Code 中创作 Agent。

注意：从 2026 年 4 月开始，Agent 的 topics 更名为 subagents（子代理），功能不变。

什么是 Agent Script？

Agent Script 是 Salesforce 为构建 Agentforce Agent 专门设计的语言。它将两种指令模式结合在单一工作流中：

逻辑指令（->） —— 每次确定性执行。用于运行动作、设置变量、if/else 条件分支。适合业务规则和程序化控制
Prompt 指令（|） —— 自然语言文本发送给 LLM。LLM 解读后决定如何回复客户。保留 LLM 的对话技能和复杂推理能力

通过表达式，你可以定义 if/else 条件、跳转和其他逻辑；设置、修改和比较变量；选择子代理和动作。例如，你可以用脚本控制 Agent 何时从一个子代理跳转到另一个，或何时按特定顺序运行动作（有时称为动作链 action chaining）。

编写 Agent Script 的三种方式

Agentforce Builder 提供多种编写方式，适应不同技能水平的用户：

对话式（Chat）：用自然语言描述需求，如"If the order total is over $100, then offer free shipping."。Agentforce 自动将需求转换为子代理、动作、指令和表达式
Canvas 视图：Agent Script 被精简为易于理解的块，可展开查看底层脚本。输入 / 添加常见表达式快捷方式，输入 @ 添加资源（子代理、动作、变量）
Script 视图（高级用户）：直接编写和编辑脚本，支持语法高亮、自动补全和验证。适合需要精确控制的场景

开发者还可以使用 Agentforce DX 生成或拉取 .agent 脚本文件到本地 Salesforce DX 项目，在 VS Code 中编辑。Agentforce DX VS Code 扩展完全支持 Agent Script 语言的标准代码编辑功能。

Agent Script 能做什么？

Agent Script 保留了自然语言 Prompt 带来的对话技能和复杂推理能力，同时增加了程序化指令的确定性。你可以在脚本中定义：

LLM 自由推理区域：使用 | prompt 指令标记 LLM 可以自主决策的范围（参见推理指令参考）
确定性执行区域：使用 -> 逻辑指令标记必须确定执行的部分
变量：可靠存储 Agent 当前状态信息，不依赖 LLM 上下文记忆。支持 string、number、boolean 类型
条件表达式：根据变量值决定执行路径或 LLM 对话内容。如根据 is_member 变量对客户说不同的话；或根据 appointment_type 确定性选择运行哪个动作
子代理跳转条件：可以确定性跳转（@utils.transition），或将跳转暴露为 LLM 可选的工具，让 LLM 自主决定何时切换子代理

示例脚本与 Agent Skills

完整 Agent Script 示例

system:
    instructions: "You are a friendly and empathetic agent that helps customers."
    messages:
        error: "Sorry, something went wrong."
        welcome: "Hello! How are you feeling today?"

config:
    agent_name: "HelloWorldBot"
    default_agent_user: "hello@world.com"

language:
    default_locale: "en_US"
    additional_locales: ""

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

关键洞察：-> 之后的逻辑包含条件判断（if/else），每个分支内通过 | 切换到 LLM prompt。这种混合模式让你获得可预测的确定性逻辑以及 LLM 推理能力的双重优势。

Agent Skills

Skills in Agentforce Vibes — Agentforce Vibes 中 Skill 的使用说明
Agentforce Vibes Library — Salesforce Agent Skills 的精选集合，适用于任何支持 Skills 的 AI 工具
Agentforce Development Skill — 专为构建、修改、调试和部署 Agentforce Agent（使用 Agent Script）设计的 Skill

学习路线

要学习如何在 Canvas 视图或对话方式下构建 Agent，参见 Build Enterprise-Ready Agents with the New Agentforce Builder。

深入学习 Agent Script：

语言特性（Language Characteristics） — 编译型、混合模式、声明式/过程式
Agent Script 块（Blocks） — System/Config/Variables/Language/Connection/Subagent
控制流（Flow of Control） — 请求处理、Prompt 构建、子代理跳转
通用模式（Patterns） — 多轮对话、动作链、条件逻辑
完整示例（Examples） — 客服、面试 Agent、术语映射
参考手册（Reference） — 语法、关键字和语义

语言特性

Agent Script 是 Salesforce 专门为构建 Agentforce Agent 而设计的语言。在深入具体语法之前，理解以下核心特性至关重要。

编译型 + 确定性 + LLM 推理

编译型语言

Agent Script 是编译型语言。当你保存 Agent 的一个版本时，脚本被编译为底层元数据供推理引擎使用。这意味着语法错误在保存时就会被发现，而非运行时，开发者体验更接近传统编程。

确定性 + LLM 推理的混合模式

这是 Agent Script 最核心的设计理念 —— 在单一工作流中融合两种截然不同的执行模型：

逻辑指令（->）：每次确定性运行。用于业务规则、运行动作、设置变量、条件分支。结果是 100% 可预测的
Prompt 指令（|）：自然语言发送给 LLM。LLM 解读这些指令并决定如何回复。保留灵活性但不如逻辑指令可控

参见 Flow of Control、Agent Script Patterns、Reasoning Instructions 了解具体的指令编写方式。

声明式 + 过程式 + 面向属性

声明式与过程式的结合

声明式（Declarative）：基本 Agent Script Blocks 类似声明式语言 —— 你直接声明"要什么"，而不是操心详细步骤。这让 Agent 的定义和定制变得简单
过程式（Procedural）：推理指令（reasoning instructions）中的逻辑部分类似过程式语言 —— 你按逻辑步骤指定"怎么做"。这让复杂的条件流程变得可控

这种双重特性让 Agent Script 既能被非开发人员理解，又能让开发人员精确控制复杂逻辑。

人类可读

Agent Script 设计目标是人类可读。即使是非开发人员也能基本理解 Agent 的工作方式和逻辑流程。

面向属性（Property-Based）

Agent Script 由属性集合组成，每个属性呈现为 key: value。key 始终在冒号左侧，value 在右侧。一些属性包含多行内容或子属性。顶级属性称为块（Block）：

# 单行属性
description: "Get account info"

# Config 块 —— 一个顶级块，包含多个子属性
config:
    developer_name: "Demo_Agent_1"
    default_agent_user: "digitalagent.demo@salesforce.com"
    agent_label: "Demo Agent"
    description: "This is my demo agent"

缩进规则、格式化与资源访问

缩进（类似 Python / YAML）

Agent Script 对空白敏感，缩进用于表示结构和属性之间的层级关系。至少使用 2 个空格或 1 个 Tab 作为缩进。但必须在整个脚本中一致使用同一缩进方式，混用空格和 Tab 会导致解析错误。同一嵌套层级的所有行必须使用相同缩进。

# 基本缩进
inputs:
    input_1: string
    input_2: string

# 逻辑指令：-> 后跟缩进指令
instructions: ->
    if @variables.ready_to_book:
        run @actions.get_account_info
            with account_id=@variables.account_id
            set @variables.hotel_code=@outputs.hotel_code

# 多行字符串：| 后跟缩进文本
instructions:|
    Welcome to our service!
    Please provide details about your request.
    I'll help you with whatever you need.

# Prompt 转义：从逻辑模式切换到 prompt 模式
instructions: ->
    | You are assessing the customer's timing.
      Follow these rules to determine what to ask:
    if @variables.Lead_Record.S4STiming != "":
        | Existing timing data found.
          Current Timing Value: {! @variables.Lead_Record.S4STiming }
          Ask: "Is that still correct?"

@ 符号资源访问

@actions.<name> —— 引用一个动作
@subagent.<name> —— 引用一个子代理
@variables.<name> —— 引用一个变量
@outputs.<name> —— 引用一个动作的输出
run 命令运行动作，with 提供输入，set 存储输出
在 Prompt 文本中引用变量：{!@variables.my_question}（必须用花括号包裹）

表达式与注释

表达式

Agent Script 使用熟悉的流程控制和运算符：

流程控制：if / else
数学运算：+、-
比较运算：==、!=、>、<、>=、<=
空值检查：is None、is not None

if @variables.count >= 10:
    run @actions.count_achieved_announcement
else:
    run @actions.count_missed_announcement

注释

使用 # 符号添加注释。脚本忽略该行 # 之后的所有内容。这是在脚本内部文档化脚本的最佳方式：

# 这是一个展示确定性行为的 Agent 示例脚本
# 以下 config 块定义 Agent 的基本元数据
config:
    developer_name: "MyAgent_1"

Agent Script 块（Blocks）

脚本由多个块（Block）组成，每个块包含一组属性。这些属性可以描述数据或过程。Agent Script 包含多种不同类型的块，每种都有特定的用途和结构规则。

System、Config 和 Variables 块

System 块

包含 Agent 的通用指令和必需消息。每个 Agent 必须定义 welcome 和 error 消息。多行消息使用 |，可通过 链接变量（{!@variables.xxx}）实现个性化。例如将用户首选名称动态注入欢迎消息：

system:
    instructions:|
        You are an AI agent. Have a friendly conversation.
    messages:
        welcome:|
            Hi {!@variables.userPreferredName}! I'm your personal shopping assistant.

            I can help you:
            - Find products and check availability
            - Track your orders
            - Process returns and refunds

            How can I assist you today?
        error: "Whoops!"

Config 块

定义 Agent 的配置参数。完整参数表：

参数	说明
`developer_name`	Salesforce API 名称（max 80 字符）。必须以字母开头，只能包含字母数字和下划线，不能以下划线结尾或包含连续下划线。组织中必须唯一
`default_agent_user`	运行此 Agent 的默认 Salesforce 用户的 API 名称或 ID。AgentforceServiceAgent 必填，AgentforceEmployeeAgent 忽略
`agent_label`	可选。Agent 的显示标签，UI 中显示。不提供时从 developer_name 自动生成
`description`	Agent 的目标和用途描述
`company`	可选。公司信息
`role`	可选。Agent 的角色。如 "Help the customer select the perfect gift."
`agent_version`	Agent 版本号，创建新版本时自动设置
`agent_type`	可选。Agent 类型：AgentforceServiceAgent（默认）或 AgentforceEmployeeAgent。从模板创建时自动设置
`enable_enhanced_event_logs`	可选。True/False。启用对话日志用于调试和监控。默认 False
`user_locale`	可选。用户区域设置

Variables 块

定义 Agent 和脚本可以使用的全局变量。使用 mutable 关键字标记可修改变量：

variables:
    string_var: mutable string = "hello world"
    hotel_info: mutable string = "Dreamforce Hotel"
    isPremiumUser: mutable boolean = False
    order_count: mutable number = 0
    customer_name: mutable string
        description: "The customer's full name"

脚本中通过 @variables.<variable_name> 引用变量。

Language、Connection 和 Start Agent 块

Language 块

language:
    default_locale: "en_US"
    additional_locales: ""
    all_additional_locales: False

支持的语言列表参见 Agentforce Language Support。

Connection 块

描述 Agent 如何与外部连接交互。例如 Enhanced Chat 连接，可与 @utils.escalate 命令配合使用：

connection messaging:
    escalation_message: "One moment while I connect you to the next available rep."
    outbound_route_type: "OmniChannelFlow"
    outbound_route_name: "agent_support_flow"
    adaptive_response_allowed: True

Start Agent 块（Agent Router）

每次客户发言都从此块开始执行。这是 Agent 的入口点，通常用于初始化变量、执行子代理分类和路由。在 Canvas 视图中称为"Agent Router"：

start_agent agent_router:
    description: "Welcome the user and determine the appropriate subagent"
    reasoning:
        instructions: |
            You are an agent router for this assistant. Welcome the guest
            and analyze their input to determine the most appropriate
            subagent to handle their request.
        actions:
            go_to_identity: @utils.transition to @subagent.Identity_Verification
                description: "Verifies user identity"
                available when @variables.verified == False
            go_to_order: @utils.transition to @subagent.Order_Management
                description: "Handles order lookup and updates"
                available when @variables.verified == True
            go_to_escalation: @utils.transition to @subagent.Escalation
                description: "Handles escalation to a human rep"
                available when @variables.verified == True and @variables.is_business_hours == True

通过 available when 条件守卫，你可以精确控制每个子代理跳转在什么状态下可用。更多关于子代理分类和路由的指导，参见 Subagent Classification and Routing。

Subagent 块详解

Subagent 块是 Agent Script 中最复杂的块类型，包含指令、逻辑和动作的全部定义。核心属性：

subagent name：使用 snake_case，精确描述子代理的范围和目的。此值不能包含空格
description：帮助推理引擎根据用户意图决定何时选择此子代理
system.instructions（可选）：覆盖系统级指令，仅对此子代理生效。可以避免与 LLM 产生冲突指令，也可以为特定子代理改变 Agent 的语气和语调
reasoning.instructions：逻辑指令 + Prompt 指令的组合，从上到下顺序处理，发给推理引擎
reasoning.actions：LLM 可用的工具列表。可以指向 agent actions、子代理跳转或变量设置
actions：定义此子代理可用的 agent 动作（description、inputs、outputs、target）

subagent Order_Management:
    description: "Handles order lookup, updates, and summaries"
    reasoning:
        instructions: ->
            if @variables.order_summary == "":
                run @actions.lookup_current_order
                    with member_email=@variables.member_email
                    set @variables.order_summary=@outputs.order_summary
            | Refer to the user by name {!@variables.member_name}.
              Show order summary: {!@variables.order_summary}.
              If they want past order info, ask for Order ID and
              use {!@actions.lookup_order}.
        actions:
            lookup_order: @actions.lookup_order
                with query = ...
                set @variables.order_summary=@outputs.order_summary
    actions:
        lookup_order:
            description: "Retrieve order details."
            inputs:
                query: string
            outputs:
                order_summary: string
            target: "flow://GetOrdersByContact"

关键区分：reasoning.actions 中的条目是暴露给 LLM 的工具（LLM 可选择使用），而顶层 actions 块只是定义了可用的动作。要让 LLM 能使用某个动作，必须在 reasoning.actions 中引用它。

Connected Subagent 块（Beta）

Beta 功能：Multi-Agent Orchestration（connected subagents）是 Beta 服务，受 Salesforce Beta Services Terms 约束。

connected_subagent 块定义一个连接，指向你 Salesforce 组织中的另一个 Agentforce Agent。你可以通过推理动作将任务委派给其他 Agent：

connected_subagent CRM_Agent:
    label: "CRM_Agent"
    target: "agentforce://X00Dfi200000dpFZ_CRM_Agent"
    loading_text: |
        Fetching CRM information....
    description: "Use this tool for any request about CRM information"
    inputs:
        EndUserLanguage: string = @variables.EndUserLanguage
        currentRecordId: string = @variables.currentRecordId

# 在 agent_router 中使用 connected subagent 作为推理动作
start_agent agent_router:
    reasoning:
        actions:
            crm_agent: @connected_subagent.CRM_Agent

Inputs 绑定规则：左侧（如 customer_id）是被连接方 Agent 定义的变量名，右侧（如 @variables.Customer_Id）是调用方 Agent 的变量。例如 customer_id: string = @variables.Customer_Id 意味着将调用方 Agent 的 Customer_Id 变量的值传给被连接 Agent 的 customer_id 变量。

在 Agent Script 中配置模型

默认情况下，Agentforce 使用组织中Setup 中选择的模型。通过 model_config 可以在 Agent 级别或 Subagent 级别覆盖默认值。

model_config:
    model: "model://sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet"

重要：在部署前，务必用你选择的模型充分测试 Agent。某些支持的模型可能不适合你的 Agent 或其使用的工具。可使用不同版本测试不同模型。

模型配置层级与多模型共存

模型配置支持三个优先级层级（从高到低）：Subagent > Agent > Org。你可以在同一个 Agent 中使用多个不同的模型：

# === Agent 级别 ===
system:
    instructions: "You are an AI Agent."
    messages:
        welcome: Hi, I'm an AI service assistant.
        error: "Sorry, something has gone wrong."
model_config:
    model: "model://sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet"

# === Subagent 级别（覆盖 Agent 级别）===
subagent ReservationManagement:
    description: "Handles requests to create new reservations"
    model_config:
        model: "model://sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet"

# === Agent Router 级别 ===
start_agent agent_router:
    description: "Welcome the user and determine the appropriate subagent"
    model_config:
        model: "model://sfdc_ai__DefaultGPT41"

多模型共存示例：

Org 使用 Salesforce 默认模型
MyTestAgent Agent 指定 Claude Haiku 4.5
HandleReservation 子代理指定 Gemini 3.1 Pro

实际运行效果：HandleReservation 子代理使用 Gemini 3.1 Pro；MyTestAgent 的其他子代理使用 Claude Haiku 4.5；同 Org 的其他 Agent 使用 Salesforce 默认模型。这个三级覆盖机制让你可以精确控制每个子代理使用最合适的模型，同时保持整体的简洁性。

一些 Agent 模板（如 Agentforce Service Agent）在 agent router 中使用 Salesforce 自有的 EinsteinHyperClassifier 模型进行子代理分类。

EinsteinHyperClassifier 模型

EinsteinHyperClassifier 是 Salesforce 自研的专有模型，通常用于 agent_router 中的子代理分类任务。

优势

比其他通用 LLM 显著更快的子代理分类速度
更高的分类准确率，特别是在处理专业分类约束和否定指令（negative instructions）时表现出色

使用限制

不能使用 before_reasoning 或 after_reasoning 块
只能使用 @utils.transition 工具，不能使用其他工具（tools）

Agent Script 控制流

理解执行顺序和控制流对于设计高质量的 Agent 至关重要。Agentforce 有三个核心执行路径：首次请求、处理子代理（构建 Prompt）、子代理之间跳转。

首次请求与子代理处理机制

首次请求（First Request）

所有请求（包括首次）都从 start_agent 块开始。Agent Router 通常用于：设置变量的初始值、执行子代理分类（告诉 LLM 根据当前上下文选择哪个子代理）。这是每次对话轮次的统一入口。

子代理处理流程

Agentforce 使用子代理的文本指令、变量、if/else 条件和其他程序化指令来构建 LLM Prompt。处理过程的核心规则：

推理指令从上到下、顺序执行
程序化逻辑和文本指令可以混合，但 LLM 只在收到最终解析后的 Prompt 后才开始推理——不是在 Agentforce 解析过程中
如果推理指令包含跳转命令（transition to），Agentforce 立即跳转到目标子代理，丢弃当前子代理中已解析的所有 Prompt 内容
最终 Prompt 只包含最后一个子代理解析出的指令

Agent Script 还支持 before_reasoning 和 after_reasoning 块，分别在推理指令处理之前和之后执行，但不受 LLM 影响。

深入示例：Agentforce 如何构建 Prompt

以下是一个完整的 Prompt 构建过程的逐步拆解。假设参数：order ID = 1234，delivery date = February 10, 2026，包裹已延迟，num_turns = 2。

subagent Order_Management:
    description: "Handles order inquiries."
    reasoning:
        instructions:->
            set @variables.num_turns = @variables.num_turns + 1
            run @actions.get_delivery_date
                with order_ID=@variables.order_ID
                set @variables.updated_delivery_date=@outputs.delivery_date

            | Tell the user that the expected delivery date for order
              number {!@variables.order_ID} is {!@variables.updated_delivery_date}

            run @actions.check_if_late
                with order_ID=@variables.order_ID
                with delivery_date=@variables.updated_delivery_date
                set @variables.is_late = @outputs.is_late

            if @variables.is_late == True:
                | Apologize to the customer for the delay in receiving
                  their order.
    after_reasoning:
        if @variables.num_turns > 5:
            transition to @subagent.escalate_order

逐行解析（共 11 步）

#	操作	结果
1	初始化 Prompt	Prompt = ""
2	`set num_turns = num_turns + 1`	num_turns: 2 → 3
3	`run get_delivery_date`	执行动作，获取 delivery_date
4	`set updated_delivery_date`	updated_delivery_date = "February 10, 2026"
5	`\| Tell the user...`	Prompt += "Tell the user that the expected delivery date for order number 1234 is February 10, 2026."
6	`run check_if_late`	执行动作，获取 is_late = True
7	`set is_late`	is_late = True
8	`if @variables.is_late == True:`	条件成立 ✓
9	`\| Apologize to the customer...`	Prompt += "Apologize to the customer for the delay..."
10	`after_reasoning`	num_turns = 3 ≤ 5 → 不触发跳转
11	发送 Prompt 给 LLM	最终 Prompt 已构建完毕

最终发送给 LLM 的 Prompt：

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.

关键洞察：LLM 收到的 Prompt 只包含文本指令（| 之后的内容），不包含任何程序化逻辑。所有 if/else/变量设置/动作调用都在 Agentforce 引擎层面完成，其结果影响哪些文本被拼接到最终 Prompt 中。

子代理之间的跳转

你可以从推理动作、推理指令或 before/after reasoning 块中执行跳转。使用 @utils.transition to 实现。

reasoning:
    actions:
        go_to_account_help: @utils.transition to @subagent.account_help
            description: "When a user needs help with account access"

跳转的核心行为

单向性：跳转后控制 不返回 前一个子代理
Prompt 丢弃：Agentforce 丢弃前一个子代理的所有已解析 Prompt 指令
重新解析：Agentforce 从头到尾读取第二个子代理
最终 Prompt：只包含第二个子代理解析出的指令

第二个子代理完成后，Agentforce 等待下一次客户发言（utterance），然后回到 start_agent 重新开始新一轮处理。这意味着每次对话轮次都是一次全新的执行周期。

管理、下载与示例

Agent Script Agent 可以通过 Salesforce 组织 UI 或命令行（Agentforce DX）进行全生命周期管理。同时提供了可下载的文档包和丰富的示例资源。

配置、部署、测试与文档下载

配置和部署

组织 UI：Configure Your Agent、Deploy Your Agents
命令行：Agentforce DX 文档、Agentforce Metadata API

测试 Agent

有多种测试方式可选，根据用例选择最佳方法：参见 Get Started With Testing Agents。务必在 Agent 发布后再次测试。

下载 Agent Script 文档

下载完整文档作为 Markdown 文件，供编程 Agent 在没有网络查询的情况下引用正确的语法、元数据部署规则和设计模式。每周四晚间（PST）更新：

下载 AgentScriptDocs.zip
解压到项目工作区或编程 Agent 的上下文源目录

文件夹	内容
`agent-script/`	语言概览、Agent Script 块、模型配置、控制流和管理 Agent
`agent-script/reference/`	Agent Script 功能的语法、关键字和语义参考
`agent-script/patterns/`	常见任务解决方案：多轮对话、动作链、条件逻辑
`agent-script/examples/`	可作为起点的完整 Agent 实现
`deploy-metadata/`	使用元数据将 Agent 部署到新组织的说明和示例

与编程 Agent 配合使用：在 CLAUDE.md 或类似上下文文件中指向解压后的文件夹，例如：Reference the Agent Script documentation in ./docs/agent-script/ for syntax and patterns.

Agent Script 示例与 Recipes

官方示例

示例	描述
Customer Support	验证身份并提供订单信息的客服 Agent。含 agent_router + Identity + Order_Management 三个子代理
Enforce Subagent Sequencing	基于步骤变量的面试 Agent，强制问题顺序同时处理自然对话。演示状态机模式
Ground Agent With Updated Terminology	使用 Knowledge + Flow 维护术语映射表，让 Agent 理解组织不断变化的行话术语，无需重建知识库

Agent Script Recipes

更多实用示例参见 Agent Script Recipes，这是一个不断增长的示例代码库。