developing-agentforce

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Script Skill

Agent Script 技能

What This Skill Is For

本技能用途

Agent Script is Salesforce's scripting language for authoring next-generation AI agents on the Atlas Reasoning Engine. Introduced in 2025 with zero training data in any AI model. Everything needed to write, modify, diagnose, or deploy Agent Script agents is in this skill's reference files.

⚠️CRITICAL: Agent Script is NOT AppleScript, JavaScript, Python, or any other language. Do NOT confuse Agent Script syntax or semantics with any other language you have been trained on.

Agent Script agents are defined by

AiAuthoringBundle

metadata — a directory with a

.agent

file containing Agent Script source that describes topics, actions, instructions, flow control, and configuration; and a

bundle-meta.xml

file containing bundle metadata. Agents process utterances by routing through topics, each with instructions and actions backed by Apex, Flows, Prompt Templates, and other types of backing logic.

This skill covers the full Agent Script lifecycle: designing agents, writing Agent Script code, validating and debugging, deploying and publishing, and testing.

Agent Script是Salesforce推出的脚本语言，用于在Atlas推理引擎上创作下一代AI代理。2025年推出时未在任何AI模型中使用训练数据。编写、修改、诊断或部署Agent Script代理所需的所有内容都在本技能的参考文件中。

⚠️重要提示： Agent Script并非AppleScript、JavaScript、Python或其他任何语言。请勿将Agent Script的语法或语义与您所了解的其他语言混淆。

Agent Script代理由

AiAuthoringBundle

元数据定义——这是一个目录，包含一个

.agent

文件（其中的Agent Script源代码描述了主题、动作、指令、流程控制和配置），以及一个

bundle-meta.xml

文件（包含包元数据）。代理通过在主题间路由来处理用户表述，每个主题都有基于Apex、Flow、Prompt Template和其他类型支持逻辑的指令和动作。

本技能覆盖Agent Script的完整生命周期：代理设计、Agent Script代码编写、验证与调试、部署与发布，以及测试。

How to Use This Skill

如何使用本技能

This file maps user intent to task domains and relevant reference files in

references/

. Detailed knowledge includes syntax rules, design patterns, CLI commands, debugging workflows, and more.

Identify user intent from task descriptions. ALWAYS read indicated reference files BEFORE starting work.

本文件将用户意图映射到任务领域以及

references/

中的相关参考文件。详细知识包括语法规则、设计模式、CLI命令、调试工作流等。

从任务描述中识别用户意图。开始工作前务必阅读指定的参考文件。

Rules That Always Apply

始终适用的规则

Always
--json
. ALWAYS include
```
--json
```
on EVERY
```
sf
```
CLI command. Do NOT pipe CLI output through
```
jq
```
or
```
2>/dev/null
```
. Read the full JSON response directly — LLMs parse JSON natively.
Verify target org. Before any org interaction, run
```
sf config get target-org --json
```
to confirm a target org is set. If none configured, ask the user to set one with
```
sf config set target-org <alias>
```
.
Diagnose before you fix. When validating/debugging agent behavior, ALWAYS
```
--use-live-actions
```
to preview authoring bundles. Send utterances then read resulting session traces to ground your understanding of the agent's behavior. Trace files reveal topic selection, action I/O, and LLM reasoning. DO NOT modify
```
.agent
```
files or backing logic without this grounding. See Validation & Debugging for trace file locations and diagnostic patterns.
Spec approval is a hard gate. Never proceed past Agent Spec creation without explicit user approval.

始终使用
--json
参数：所有
```
sf
```
CLI命令都必须包含
```
--json
```
参数。请勿将CLI输出通过
```
jq
```
管道处理或使用
```
2>/dev/null
```
。直接读取完整的JSON响应——LLM可原生解析JSON。
验证目标组织：在与任何组织交互前，运行
```
sf config get target-org --json
```
确认已设置目标组织。如果未配置，请要求用户通过
```
sf config set target-org <alias>
```
进行设置。
先诊断再修复：验证/调试代理行为时，务必使用
--use-live-actions
参数来预览创作包。发送表述后，读取生成的会话跟踪信息，以深入了解代理的行为。跟踪文件会揭示主题选择、动作输入输出以及LLM推理逻辑。没有这些基础信息，请勿修改
.agent
文件或支持逻辑。有关跟踪文件位置和诊断模式，请参阅验证与调试。
Agent Spec审核是硬性门槛：未获得用户明确批准，请勿在创建Agent Spec后继续后续步骤。

Task Domains

任务领域

Every task domain below has Required Steps. Follow verbatim, in order. Do not substitute your own plan or skip steps.

以下每个任务领域都有必填步骤。请严格按顺序执行，不要替换自己的计划或跳过步骤。

Create an Agent

创建代理

User wants to build new agent from scratch. ALWAYS use Agent Script. Work with User to understand the agent's purpose, topics, and actions using plain language without Salesforce-specific terminology.

用户希望从头构建新代理。务必使用Agent Script。与用户协作，用非Salesforce专属术语的通俗语言理解代理的用途、主题和动作。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Design — Read Design & Agent Spec to draft an Agent Spec. Always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading
```
sfdx-project.json
```
to identify package directories, then search each for
```
@InvocableMethod
```
in
```
classes/
```
,
```
AutoLaunchedFlow
```
in
```
flows/
```
, and template metadata in
```
promptTemplates/
```
. Mark matches
```
EXISTS
```
; unmatched actions
```
NEEDS STUB
```
. Also scan
```
objects/
```
for
```
.object-meta.xml
```
to discover custom objects — related objects often contain data the agent should expose even when not mentioned in the prompt. Always save Agent Spec as file.
STOP for user approval of Agent Spec. Present to user. Ask for approval or feedback. Do not proceed without approval. Once approved, proceed without stopping unless a step fails.
Validate environment prerequisites — Read Design & Agent Spec, Section 3 (Environment Prerequisites). Based on agent type from design, validate org environment:
- Employee agent: Confirm config block does NOT include
```
default_agent_user
```
  ,
```
connection messaging:
```
  , or MessagingSession linked variables. Remove if present. See Examples for a complete employee agent example.
- Service agent: Query org for Einstein Agent User. If one exists, confirm username with user. If none, guide user through creation. See CLI for Agents, Section 12 for creation steps and Agent User Setup for required permissions. Do not proceed to code generation until environment is validated.

Generate authoring bundle —

sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>

Write code — Read Core Language for syntax, block structure, and anti-patterns. Edit generated
```
.agent
```
file using reference files and templates. Do not create
```
.agent
```
or
```
bundle-meta.xml
```
files manually.
Validate compilation —
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
If validation fails, read Validation & Debugging to diagnose and fix, then re-validate. ALWAYS fix syntax and structural errors before generating backing logic.
Generate backing logic — For each action marked NEEDS STUB:
```
sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes
```
Replace class body with invocable pattern from Design & Agent Spec. ALWAYS deploy:
```
sf project deploy start --json --metadata ApexClass:<ClassName>
```
ALWAYS fix deploy errors BEFORE generating and deploying next stub.
Validate behavior — Read Validation & Debugging for preview workflow and session trace analysis.
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
If actions query data, ground test utterances with:
```
sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100"
```
Send test utterances with:
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
Confirm topic routing, gating, and action invocations match Agent Spec. If behavior diverges, switch to Diagnose Behavioral Issues workflow. Return AFTER correcting issues. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
- ```
validate authoring-bundle
```
  passes with zero errors
- Live preview (
```
--use-live-actions
```
  ) tested with representative utterances per topic
- Traces confirm correct topic routing and action invocation
- User explicitly approves deployment
Publish — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number.
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
If publish fails, follow troubleshooting checklist in Metadata & Lifecycle, Section 5 before retrying.

Activate — Makes new version available to users.

sf agent activate --json --api-name <Developer_Name>

Verify published agent — Preview user-facing behavior AFTER activation with

sf agent preview start --json --api-name <Developer_Name>

Use

--api-name

, not

--authoring-bundle

Configure end-user access — ONLY for employee agents. Read Agent Access Guide to configure perms and assign access.

阅读代理CLI指南获取准确的命令语法。

设计——阅读设计与Agent Spec以草拟Agent Spec。务必询问是否需要扫描现有支持逻辑。除非另有指示，否则通过读取
```
sfdx-project.json
```
识别包目录，然后在每个目录中搜索
```
classes/
```
中的
```
@InvocableMethod
```
、
```
flows/
```
中的
```
AutoLaunchedFlow
```
以及
```
promptTemplates/
```
中的模板元数据。将匹配项标记为
```
EXISTS
```
；未匹配的动作标记为
```
NEEDS STUB
```
。同时扫描
```
objects/
```
中的
```
.object-meta.xml
```
以发现自定义对象——相关对象通常包含代理应暴露的数据，即使提示中未提及。务必将Agent Spec保存为文件。
暂停以等待用户审核Agent Spec。将Agent Spec呈现给用户，请求批准或反馈。未获得批准请勿继续。获得批准后，除非步骤失败，否则无需暂停继续执行。
验证环境先决条件——阅读设计与Agent Spec第3节（环境先决条件）。根据设计的代理类型，验证组织环境：
- 员工代理：确认配置块不包含
```
default_agent_user
```
  、
```
connection messaging:
```
  或MessagingSession关联变量。如果存在，请移除。完整的员工代理示例请参阅示例。
- 服务代理：查询组织中的Einstein Agent User。如果存在，请与用户确认用户名。如果不存在，引导用户完成创建步骤。创建步骤请参阅代理CLI指南第12节，所需权限请参阅代理用户设置。 环境验证通过前，请勿进入代码生成阶段。

生成创作包——

sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>

编写代码——阅读核心语言了解语法、块结构和反模式。使用参考文件和模板编辑生成的
```
.agent
```
文件。请勿手动创建
```
.agent
```
或
```
bundle-meta.xml
```
文件。
验证编译——
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
如果验证失败，请阅读验证与调试进行诊断和修复，然后重新验证。生成支持逻辑前，务必修复所有语法和结构错误。
生成支持逻辑——对于每个标记为NEEDS STUB的动作：
```
sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes
```
使用设计与Agent Spec中的可调用模式替换类主体。务必部署：
```
sf project deploy start --json --metadata ApexClass:<ClassName>
```
生成并部署下一个存根前，务必修复所有部署错误。
验证行为——阅读验证与调试了解预览工作流和会话跟踪分析。
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
如果动作需要查询数据，请使用以下命令为测试表述提供数据基础：
```
sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100"
```
使用以下命令发送测试表述：
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
确认主题路由、门控和动作调用与Agent Spec一致。如果行为不符，请切换到诊断行为问题工作流。修复问题后再返回。 检查点——满足以下所有条件后，才能进入发布阶段：
- ```
validate authoring-bundle
```
  零错误通过
- 使用代表性表述对每个主题进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认主题路由和动作调用正确
- 用户明确批准部署
发布——发布操作仅验证元数据结构，不验证代理行为。每次发布都会创建永久版本号。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
如果发布失败，请先遵循元数据与生命周期第5节中的故障排除清单，然后重试。

激活——使新版本对用户可用。

sf agent activate --json --api-name <Developer_Name>

验证已发布代理——激活后，使用以下命令预览面向用户的行为：
```
sf agent preview start --json --api-name <Developer_Name>
```
使用
```
--api-name
```
参数，而非
```
--authoring-bundle
```
。
配置终端用户访问权限——仅适用于员工代理。阅读代理访问指南配置权限并分配访问权。

Reference Files

参考文件

CLI for Agents — exact command syntax for generate, validate, deploy, publish, activate; Section 12 for Einstein Agent User creation
Core Language — execution model, syntax, block structure, anti-patterns
Design & Agent Spec — topic graph design, flow control patterns, Agent Spec production, backing logic analysis; Section 3 for environment prerequisites
Topic Map Diagrams — Mermaid diagram conventions for visualizing the agent's topic graph
Agent User Setup & Permissions — permission set assignment, object permissions, cross-topic validation
Metadata & Lifecycle — directory structure, bundle metadata; publish troubleshooting
Validation & Debugging — validate the agent compiles, preview to confirm behavior
Agent Access Guide — end-user access permissions, visibility troubleshooting
Known Issues — only load when errors persist after code fixes
Architecture Patterns — hub-and-spoke, verification gate, post-action loop
Complex Data Types — type mapping decision tree
Safety Review — 7-category safety review
Discover Reference — target discovery CLI
Scaffold Reference — stub generation CLI
Deploy Reference — deployment lifecycle, error recovery

代理CLI指南——生成、验证、部署、发布、激活的准确命令语法；第12节为Einstein Agent User创建步骤
核心语言——执行模型、语法、块结构、反模式
设计与Agent Spec——主题图设计、流程控制模式、Agent Spec生成、支持逻辑分析；第3节为环境先决条件
主题图图表——用于可视化代理主题图的Mermaid图表约定
代理用户设置与权限——权限集分配、对象权限、跨主题验证
元数据与生命周期——目录结构、包元数据；发布故障排除
验证与调试——验证代理编译、预览以确认行为
代理访问指南——终端用户访问权限、可见性故障排除
已知问题——仅在代码修复后错误仍存在时查阅
架构模式——中心辐射型、验证门控、动作后循环
复杂数据类型——类型映射决策树
安全审核——7类安全审核
发现参考——目标发现CLI
脚手架参考——存根生成CLI
部署参考——部署生命周期、错误恢复

Comprehend an Existing Agent

理解现有代理

User wants to understand Agent Script agent they didn't write or need to revisit. May point to

AiAuthoringBundle

directory or ask "what does this agent do?" or "I need to fix this agent but I don't understand how it works.".

用户希望了解自己未编写或需要重新审视的Agent Script代理。可能指向

AiAuthoringBundle

目录，或询问“这个代理是做什么的？”或“我需要修复这个代理，但我不知道它是如何工作的。”

Required Steps

必填步骤

Locate agent — Read
```
sfdx-project.json
```
to identify package directories. Find
```
AiAuthoringBundle
```
directory within them. Read
```
.agent
```
file and
```
bundle-meta.xml
```
.
Read code — Read Core Language for syntax and execution model BEFORE parsing
```
.agent
```
file.
Map backing logic — For each action with
```
target
```
, locate backing implementation (Apex class, Flow, Prompt Template) in project. Note input/output contracts.
Reverse-engineer Agent Spec — Read Design & Agent Spec for Agent Spec structure. Produce Agent Spec from code and save as file.
Produce Topic Map diagram — Read Topic Map Diagrams for Mermaid conventions. Generate flowchart of topic graph showing transitions, gates, and action associations.
Annotate source — Ask if user wants Agent Script source annotated with explanations. If requested, add inline comments to
```
.agent
```
file explaining flow control decisions, gating rationale, and topic relationships.
Present to user — Share Agent Spec, Topic Map, and annotated source if produced. Check Anti-Patterns section in Core Language reference and flag any matches found in code.

定位代理——读取
```
sfdx-project.json
```
识别包目录，在其中找到
```
AiAuthoringBundle
```
目录，读取
```
.agent
```
文件和
```
bundle-meta.xml
```
文件。
阅读代码——在解析
```
.agent
```
文件前，先阅读核心语言了解语法和执行模型。
映射支持逻辑——对于每个带有
```
target
```
的动作，在项目中找到对应的支持实现（Apex类、Flow、Prompt Template），记录输入/输出契约。
反向工程Agent Spec——阅读设计与Agent Spec了解Agent Spec结构，根据代码生成Agent Spec并保存为文件。
生成主题图——阅读主题图图表了解Mermaid约定，生成主题图流程图，展示主题间的转换、门控和动作关联。
注释源代码——询问用户是否需要为Agent Script源代码添加解释注释。如果需要，在
```
.agent
```
文件中添加内联注释，解释流程控制决策、门控依据和主题关系。
向用户呈现结果——分享生成的Agent Spec、主题图（如有）和带注释的源代码。检查核心语言参考中的反模式部分，标记代码中发现的任何匹配项。

Reference Files

参考文件

Core Language — syntax, execution model, anti-patterns
Design & Agent Spec — Agent Spec structure, flow control pattern recognition
Topic Map Diagrams — Mermaid conventions for topic graph visualization
Metadata & Lifecycle — directory conventions, bundle metadata
Known Issues — only load when code contains unexplained workaround patterns

核心语言——语法、执行模型、反模式
设计与Agent Spec——Agent Spec结构、流程控制模式识别
主题图图表——主题图可视化的Mermaid约定
元数据与生命周期——目录约定、包元数据
已知问题——仅在代码包含无法解释的变通模式时查阅

Modify an Existing Agent

修改现有代理

User wants to add, remove, or change topics, actions, instructions, or flow control on existing agent. May describe change in plain language ("add a billing topic") or reference specific Agent Script constructs.

用户希望在现有代理中添加、移除或修改主题、动作、指令或流程控制。可能用通俗语言描述变更（如“添加账单主题”），或引用特定的Agent Script结构。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Comprehend — If no Agent Spec exists, reverse-engineer first by following "Comprehend an Existing Agent" workflow above.
Update Agent Spec — Read Design & Agent Spec for flow control patterns and backing logic analysis. Modify Agent Spec to reflect intended changes. For new actions, always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading
```
sfdx-project.json
```
to identify package directories, then search each for
```
@InvocableMethod
```
in
```
classes/
```
,
```
AutoLaunchedFlow
```
in
```
flows/
```
, and template metadata in
```
promptTemplates/
```
. Mark matches
```
EXISTS
```
; unmatched actions
```
NEEDS STUB
```
. Always save updated Agent Spec as file.
STOP for user approval of updated Agent Spec. Present to user. Ask for approval or feedback. Do not proceed without approval. Once approved, proceed without stopping unless a step fails.
Edit code — Read Core Language for syntax and anti-patterns. Edit
```
.agent
```
file to implement approved changes.
Validate compilation —
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
If validation fails, read Validation & Debugging to diagnose and fix, then re-validate.
Generate new backing logic — For each new action marked NEEDS STUB:
```
sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes
```
Replace class body with invocable pattern from Design & Agent Spec. ALWAYS deploy:
```
sf project deploy start --json --metadata ApexClass:<ClassName>
```
ALWAYS fix deploy errors BEFORE generating and deploying next stub. Skip if no new actions added.
Validate behavior — Read Validation & Debugging for preview workflow and session trace analysis.
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
If actions query data, ground test utterances with:
```
sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100"
```
Send test utterances with:
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
Test changed paths first, then adjacent paths to catch regressions in existing behavior. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
- ```
validate authoring-bundle
```
  passes with zero errors
- Live preview (
```
--use-live-actions
```
  ) tested with representative utterances per topic
- Traces confirm correct topic routing and action invocation
- User explicitly approves deployment
Publish — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number.
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
If publish fails, follow troubleshooting checklist in Metadata & Lifecycle, Section 5 before retrying.

Activate — Makes new version available to users.

sf agent activate --json --api-name <Developer_Name>

Verify published agent — Preview user-facing behavior AFTER activation with

sf agent preview start --json --api-name <Developer_Name>

Use

--api-name

, not

--authoring-bundle

阅读代理CLI指南获取准确的命令语法。

理解代理——如果没有Agent Spec，先遵循“理解现有代理”工作流进行反向工程。
更新Agent Spec——阅读设计与Agent Spec了解流程控制模式和支持逻辑分析。修改Agent Spec以反映预期变更。对于新动作，务必询问是否需要扫描现有支持逻辑。除非另有指示，否则通过读取
```
sfdx-project.json
```
识别包目录，然后在每个目录中搜索
```
classes/
```
中的
```
@InvocableMethod
```
、
```
flows/
```
中的
```
AutoLaunchedFlow
```
以及
```
promptTemplates/
```
中的模板元数据。将匹配项标记为
```
EXISTS
```
；未匹配的动作标记为
```
NEEDS STUB
```
。务必将更新后的Agent Spec保存为文件。
暂停以等待用户审核更新后的Agent Spec。将Agent Spec呈现给用户，请求批准或反馈。未获得批准请勿继续。获得批准后，除非步骤失败，否则无需暂停继续执行。
编辑代码——阅读核心语言了解语法和反模式。编辑
```
.agent
```
文件以实现已批准的变更。
验证编译——
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
如果验证失败，请阅读验证与调试进行诊断和修复，然后重新验证。
生成新的支持逻辑——对于每个新的标记为NEEDS STUB的动作：
```
sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes
```
使用设计与Agent Spec中的可调用模式替换类主体。务必部署：
```
sf project deploy start --json --metadata ApexClass:<ClassName>
```
生成并部署下一个存根前，务必修复所有部署错误。如果未添加新动作，可跳过此步骤。
验证行为——阅读验证与调试了解预览工作流和会话跟踪分析。
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
如果动作需要查询数据，请使用以下命令为测试表述提供数据基础：
```
sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100"
```
使用以下命令发送测试表述：
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
先测试变更路径，再测试相邻路径，以发现现有行为中的回归问题。 检查点——满足以下所有条件后，才能进入发布阶段：
- ```
validate authoring-bundle
```
  零错误通过
- 使用代表性表述对每个主题进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认主题路由和动作调用正确
- 用户明确批准部署
发布——发布操作仅验证元数据结构，不验证代理行为。每次发布都会创建永久版本号。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
如果发布失败，请先遵循元数据与生命周期第5节中的故障排除清单，然后重试。

激活——使新版本对用户可用。

sf agent activate --json --api-name <Developer_Name>

验证已发布代理——激活后，使用以下命令预览面向用户的行为：
```
sf agent preview start --json --api-name <Developer_Name>
```
使用
```
--api-name
```
参数，而非
```
--authoring-bundle
```
。

Reference Files

参考文件

CLI for Agents — exact command syntax for validate, deploy, preview, publish, activate
Core Language — syntax, anti-patterns
Design & Agent Spec — Agent Spec updates, backing logic analysis
Validation & Debugging — compilation diagnosis, preview workflow, session trace analysis
Known Issues — only load when errors persist after code fixes

代理CLI指南——验证、部署、预览、发布、激活的准确命令语法
核心语言——语法、反模式
设计与Agent Spec——Agent Spec更新、支持逻辑分析
验证与调试——编译诊断、预览工作流、会话跟踪分析
已知问题——仅在代码修复后错误仍存在时查阅

Diagnose Compilation Errors

诊断编译错误

User has Agent Script that won't compile. Errors surface from

sf agent validate

sf agent preview start

, or User describes symptoms like "I'm getting a validation error."

用户的Agent Script无法编译。错误来自

sf agent validate

或

sf agent preview start

命令，或用户描述类似“我遇到了验证错误”的症状。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Reproduce error — Run
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
to capture basic compile errors. If no errors, run
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
to capture complex compile errors. If user provides specific error output, ALWAYS reproduce to confirm.
Classify error — Read Validation & Debugging for error taxonomy. Map each error message to root cause category.
Locate fault — Read Core Language to understand correct syntax. Find specific line(s) in
```
.agent
```
file that cause each error.
Fix code — Apply targeted fixes. Check Anti-Patterns section in Core Language reference to ensure you're not introducing known bad pattern.

Re-validate — Run

sf agent validate authoring-bundle --json --api-name <Developer_Name>

then run

sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>

Repeat steps 2–5 if errors persist.

Explain fix — Tell user what was wrong and what you changed. Explain root cause in terms of Core Language agent execution model.

阅读代理CLI指南获取准确的命令语法。

重现错误——运行
```
sf agent validate authoring-bundle --json --api-name <Developer_Name>
```
捕获基本编译错误。如果没有错误，运行
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
捕获复杂编译错误。如果用户提供了特定错误输出，务必重现以确认。
分类错误——阅读验证与调试了解错误分类，将每个错误消息映射到根本原因类别。
定位故障点——阅读核心语言了解正确语法，找到
```
.agent
```
文件中导致每个错误的具体行。
修复代码——应用针对性修复。检查核心语言参考中的反模式部分，确保未引入已知的不良模式。

重新验证——运行

sf agent validate authoring-bundle --json --api-name <Developer_Name>

然后运行

sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>

如果错误仍然存在，重复步骤2-5。

解释修复方案——告知用户问题所在以及所做的更改，从核心语言代理执行模型的角度解释根本原因。

Reference Files

参考文件

Core Language — syntax, block structure, anti-patterns
Validation & Debugging — error taxonomy, error-to-root-cause mapping
Known Issues — only load when error doesn't match user code; may be a platform bug
Production Gotchas — only load when error involves reserved keywords or lifecycle hook syntax

核心语言——语法、块结构、反模式
验证与调试——错误分类、错误到根本原因的映射
已知问题——仅在错误与用户代码不匹配时查阅，可能是平台漏洞
生产注意事项——仅在错误涉及保留关键字或生命周期钩子语法时查阅

Diagnose Behavioral Issues

诊断行为问题

Agent compiles, preview can start and

--use-live-actions

, but agent does not behave as expected. User describes symptoms like "the agent keeps going to the wrong topic" or "the action isn't being called." Fundamentally different from

validate

preview start

errors — code is valid but behavior is wrong.

代理可编译，预览可启动且使用

--use-live-actions

参数，但代理行为不符合预期。用户描述的症状如“代理总是跳转到错误的主题”或“动作未被调用”。这与

validate

或

preview start

错误完全不同——代码有效但行为异常。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Establish baseline — Read Agent Spec. If no Agent Spec exists, follow Comprehend an Existing Agent workflow to reverse-engineer one, then continue.
Form hypotheses — Read Core Language for execution model. Based on user's description, list candidate root causes. Think through: topic routing, gating conditions, action availability, instruction clarity, variable state, and transition timing.
Reproduce in preview — Read Validation & Debugging for preview workflow and session trace analysis. Start preview session:
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
then send test messages covering EACH topic with
```
sf agent preview send
```
. One message is not enough — confirm behavior per topic before proceeding.
Analyze session traces — Examine trace output to confirm topic selection, action availability/execution, LLM reasoning, and where behavior diverges from Agent Spec. Do NOT skip this step — preview output alone is insufficient for diagnosis.
Identify root cause — Match trace evidence to hypotheses. Consult Core Language reference and Gating Patterns in Design & Agent Spec reference to confirm absence of anti-patterns.
Fix code — Apply targeted fix. If fix involves flow control changes, update Agent Spec to match.
Re-validate and re-preview — Repeat steps 3–6 until behavior matches Agent Spec or you confirm a platform limitation. Run
```
validate authoring-bundle
```
, then
```
preview start --use-live-actions
```
to verify fix using same utterances. Then test adjacent paths that might be affected by your changes.
Explain fix — Tell user what was wrong and what you changed. Explain root cause in terms of Core Language agent execution model.

阅读代理CLI指南获取准确的命令语法。

建立基准——阅读Agent Spec。如果没有Agent Spec，先遵循“理解现有代理”工作流进行反向工程，然后继续。
形成假设——阅读核心语言了解执行模型。根据用户描述，列出可能的根本原因候选，思考：主题路由、门控条件、动作可用性、指令清晰度、变量状态和转换时机。
在预览中重现问题——阅读验证与调试了解预览工作流和会话跟踪分析。启动预览会话：
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
然后使用
```
sf agent preview send
```
发送覆盖每个主题的测试消息。仅发送一条消息不够——在继续前确认每个主题的行为。
分析会话跟踪信息——检查跟踪输出，确认主题选择、动作可用性/执行、LLM推理，以及行为与Agent Spec的差异点。请勿跳过此步骤——仅预览输出不足以进行诊断。
确定根本原因——将跟踪证据与假设匹配。查阅核心语言参考和设计与Agent Spec中的门控模式，确认不存在反模式。
修复代码——应用针对性修复。如果修复涉及流程控制变更，请更新Agent Spec以匹配。
重新验证和预览——重复步骤3-6，直到行为与Agent Spec一致，或确认存在平台限制。运行
```
validate authoring-bundle
```
，然后运行
```
preview start --use-live-actions
```
，使用相同的表述验证修复效果。然后测试可能受变更影响的相邻路径。
解释修复方案——告知用户问题所在以及所做的更改，从核心语言代理执行模型的角度解释根本原因。

Reference Files

参考文件

Core Language — execution model, anti-patterns
Design & Agent Spec — Agent Spec as behavioral baseline, gating patterns
Validation & Debugging — preview workflow, session trace analysis
Known Issues — only load when behavior is wrong but code logic is correct

核心语言——执行模型、反模式
设计与Agent Spec——作为行为基准的Agent Spec、门控模式
验证与调试——预览工作流、会话跟踪分析
已知问题——仅在行为异常但代码逻辑正确时查阅

Deploy, Publish, and Activate

部署、发布与激活

User wants to take working agent from local development to running state in Salesforce org. Involves deploying

AiAuthoringBundle

and its dependencies, publishing to commit version, then activating to make it live.

用户希望将可用的代理从本地开发环境部署到Salesforce组织的运行状态。涉及部署

AiAuthoringBundle

及其依赖项、发布以提交版本，然后激活使其生效。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Validate compilation —

sf agent validate authoring-bundle --json --api-name <Developer_Name>

Do not proceed if validation fails.

Deploy bundle and dependencies — Read Metadata & Lifecycle for dependency management and deploy commands. Deploy
```
AiAuthoringBundle
```
and all backing logic (Apex classes, Flows, Prompt Templates) and dependencies to org.
Live preview — Read Validation & Debugging for preview workflow and session trace analysis.
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
then send test utterances with:
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
Test key conversation paths to validate agent behavior when backed by live actions. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
- ```
validate authoring-bundle
```
  passes with zero errors
- Live preview (
```
--use-live-actions
```
  ) tested with representative utterances per topic
- Traces confirm correct topic routing and action invocation
- User explicitly approves deployment
Publish — Publish validates metadata structure, not agent behavior. DO NOT publish as part of a dev/test inner loop. ONLY publish as the FINAL step prior to activating the agent and surfacing it to end users.
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
If publish fails, follow Troubleshooting Publish Failures in Metadata & Lifecycle before retrying.

Activate — Makes new version available to users.

sf agent activate --json --api-name <Developer_Name>

Verify published agent — Preview user-facing behavior AFTER activation with

sf agent preview start --json --api-name <Developer_Name>

Use

--api-name

, not

--authoring-bundle

Configure end-user access — ONLY for employee agents. Read Agent Access Guide to configure perms and assign access.

阅读代理CLI指南获取准确的命令语法。

验证编译——

sf agent validate authoring-bundle --json --api-name <Developer_Name>

如果验证失败，请勿继续。

部署包和依赖项——阅读元数据与生命周期了解依赖管理和部署命令，将
```
AiAuthoringBundle
```
及其所有支持逻辑（Apex类、Flow、Prompt Template）和依赖项部署到组织。
实时预览——阅读验证与调试了解预览工作流和会话跟踪分析。
```
sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>
```
然后使用以下命令发送测试表述：
```
sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"
```
测试关键对话路径，验证代理在实时动作支持下的行为。 检查点——满足以下所有条件后，才能进入发布阶段：
- ```
validate authoring-bundle
```
  零错误通过
- 使用代表性表述对每个主题进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认主题路由和动作调用正确
- 用户明确批准部署
发布——发布操作仅验证元数据结构，不验证代理行为。请勿在开发/测试内部循环中进行发布操作。仅在激活代理并向终端用户公开前的最后一步进行发布。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
如果发布失败，请先遵循元数据与生命周期中的“发布故障排除”步骤，然后重试。

激活——使新版本对用户可用。

sf agent activate --json --api-name <Developer_Name>

验证已发布代理——激活后，使用以下命令预览面向用户的行为：
```
sf agent preview start --json --api-name <Developer_Name>
```
使用
```
--api-name
```
参数，而非
```
--authoring-bundle
```
。
配置终端用户访问权限——仅适用于员工代理。阅读代理访问指南配置权限并分配访问权。

Reference Files

参考文件

CLI for Agents — exact command syntax for deploy, publish, activate, deactivate
Validation & Debugging — compilation validation, preview workflow
Metadata & Lifecycle — dependency management, deploy commands; publish troubleshooting
Agent Access Guide — end-user access permissions, visibility troubleshooting
Known Issues — only load when deploy hangs, publish fails, or activate fails unexpectedly

代理CLI指南——部署、发布、激活、停用的准确命令语法
验证与调试——编译验证、预览工作流
元数据与生命周期——依赖管理、部署命令；发布故障排除
代理访问指南——终端用户访问权限、可见性故障排除
已知问题——仅在部署挂起、发布失败或激活意外失败时查阅

Diagnose Production Issues

诊断生产环境问题

User's agent is published and active but experiencing issues not caught during preview. Includes credit overconsumption, token or size limit failures, loop guardrail interruptions, reserved keyword runtime errors, VS Code sync failures, or unexpected behavioral differences between preview and production.

用户的代理已发布并激活，但遇到了预览阶段未发现的问题。包括信用过度消耗、令牌或大小限制失败、循环护栏中断、保留关键字运行时错误、VS Code同步失败，或预览与生产环境之间的意外行为差异。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Classify issue — Determine whether this is billing/cost concern, runtime limit, naming conflict, tooling issue, or behavioral difference between preview and production.
Check known production gotchas — Read Production Gotchas for credit consumption, token limits, loop guardrails, reserved keywords, lifecycle hooks, and VS Code workarounds.
Compare preview vs production behavior — If issue is behavioral, preview published agent with
```
sf agent preview start --json --api-name <Developer_Name>
```
(not
```
--authoring-bundle
```
). Compare against live-actions authoring bundle preview
```
--authoring-bundle <Developer_Name> --use-live-actions
```
to isolate preview-vs-production differences.
Check known issues — Read Known Issues for platform bugs that may explain production-only failures.
Fix and republish — Apply fixes, validate, re-preview, publish, activate, verify. Follow Deploy, Publish, and Activate steps.
Explain diagnosis — Tell user what was happening and what you changed. Explain root cause.

阅读代理CLI指南获取准确的命令语法。

分类问题——确定这是计费/成本问题、运行时限制、命名冲突、工具问题，还是预览与生产环境之间的行为差异。
查阅已知生产注意事项——阅读生产注意事项了解信用消耗、令牌限制、循环护栏、保留关键字、生命周期钩子和VS Code变通方案。
比较预览与生产环境行为——如果是行为问题，使用以下命令预览已发布的代理：
```
sf agent preview start --json --api-name <Developer_Name>
```
（而非
```
--authoring-bundle
```
）。与使用
```
--authoring-bundle <Developer_Name> --use-live-actions
```
参数的实时动作创作包预览进行比较，以隔离预览与生产环境的差异。
查阅已知问题——阅读已知问题了解可能导致生产环境独有故障的平台漏洞。
修复并重新发布——应用修复、验证、重新预览、发布、激活、验证。遵循部署、发布与激活步骤。
解释诊断结果——告知用户发生了什么以及所做的更改，解释根本原因。

Reference Files

参考文件

Production Gotchas — credit consumption, token limits, loop guardrails, reserved keywords, lifecycle hooks, VS Code workarounds
CLI for Agents — command syntax for preview, publish, activate
Validation & Debugging — preview workflow, session trace analysis
Known Issues — only load when issue may be a platform bug

生产注意事项——信用消耗、令牌限制、循环护栏、保留关键字、生命周期钩子、VS Code变通方案
代理CLI指南——预览、发布、激活的命令语法
验证与调试——预览工作流、会话跟踪分析
已知问题——仅在问题可能是平台漏洞时查阅

Delete or Rename an Agent

删除或重命名代理

User wants to remove agent or change its name. Maintenance tasks complicated by

AiAuthoringBundle

versioning and published version dependencies.

用户希望移除代理或更改其名称。由于

AiAuthoringBundle

的版本控制和已发布版本的依赖关系，这些维护任务较为复杂。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Understand current state — Read Metadata & Lifecycle for versioning, delete mechanics, and rename mechanics. Identify whether agent has been published, how many versions exist, and whether it's currently active.
Deactivate if active —
```
sf agent deactivate --json --api-name <Developer_Name>
```
Active agent cannot be deleted or renamed.
Execute operation — For delete: follow delete mechanics in Metadata & Lifecycle reference. For rename: follow rename mechanics in same reference.
Clean up orphans — Check for and remove orphaned metadata: Bot, BotVersion, GenAiPlannerBundle, GenAiPlugin, GenAiFunction. Metadata & Lifecycle reference details what to look for.
Validate — Confirm operation completed cleanly. For rename, validate new bundle compiles and preview to confirm behavior.

阅读代理CLI指南获取准确的命令语法。

了解当前状态——阅读元数据与生命周期了解版本控制、删除机制和重命名机制，确定代理是否已发布、存在多少版本以及当前是否处于激活状态。
如果处于激活状态，先停用——
```
sf agent deactivate --json --api-name <Developer_Name>
```
激活状态的代理无法删除或重命名。
执行操作——删除操作：遵循元数据与生命周期参考中的删除机制。重命名操作：遵循同一参考中的重命名机制。
清理孤立元数据——检查并移除孤立的元数据：Bot、BotVersion、GenAiPlannerBundle、GenAiPlugin、GenAiFunction。元数据与生命周期参考详细说明了需要检查的内容。
验证——确认操作已顺利完成。对于重命名操作，验证新包可编译并预览以确认行为。

Reference Files

参考文件

CLI for Agents — exact command syntax for delete, deactivate, retrieve
Validation & Debugging — compilation validation, preview workflow
Metadata & Lifecycle — delete mechanics, rename mechanics, orphan cleanup

代理CLI指南——删除、停用、检索的准确命令语法
验证与调试——编译验证、预览工作流
元数据与生命周期——删除机制、重命名机制、孤立元数据清理

Test an Agent

测试代理

User wants to create automated tests for Agent Script agent. Involves writing

AiEvaluationDefinition

test specs in YAML format that define test scenarios, expected behaviors, and quality metrics.

用户希望为Agent Script代理创建自动化测试。涉及编写YAML格式的

AiEvaluationDefinition

测试规范，定义测试场景、预期行为和质量指标。

Required Steps

必填步骤

Read CLI for Agents for exact command syntax.

Establish coverage baseline — Read Agent Spec. If no Agent Spec exists, reverse-engineer first by following Comprehend steps. Map every topic, action, and flow control path to identify what needs test coverage.
Design test scenarios — For test design methodology, expectations, metrics, test spec YAML format, and templates, use testing-agentforce skill. That skill owns all testing content. For each coverage target, write one or more test scenarios: user utterance, expected topic routing, expected action invocations, and expected agent response. Include both happy paths and edge cases.
Write test spec YAML — Use template and reference files from testing-agentforce skill. Save to
```
specs/<Agent_API_Name>-testSpec.yaml
```
in SFDX project.
Create test metadata — Generate
```
AiEvaluationDefinition
```
from test spec using CLI.
Deploy test — Deploy
```
AiEvaluationDefinition
```
to org.
Run tests — Execute test run using CLI. Capture results.
Analyze results — Compare actual outcomes against expectations. For failures, identify whether issue is in agent code, backing logic, or test spec itself.
Iterate — Fix agent code or test spec as needed, redeploy, and re-run until coverage targets are met.

阅读代理CLI指南获取准确的命令语法。

建立覆盖基准——阅读Agent Spec。如果没有Agent Spec，先遵循“理解现有代理”步骤进行反向工程。映射每个主题、动作和流程控制路径，确定需要测试覆盖的内容。
设计测试场景——测试设计方法、预期结果、指标、测试规范YAML格式和模板，请使用testing-agentforce技能。该技能负责所有测试相关内容。对于每个覆盖目标，编写一个或多个测试场景：用户表述、预期主题路由、预期动作调用和预期代理响应。包括正常路径和边缘情况。
编写测试规范YAML——使用testing-agentforce技能中的模板和参考文件，保存到SFDX项目的
```
specs/<Agent_API_Name>-testSpec.yaml
```
中。
创建测试元数据——使用CLI从测试规范生成
```
AiEvaluationDefinition
```
。
部署测试——将
```
AiEvaluationDefinition
```
部署到组织。
运行测试——使用CLI执行测试运行，捕获结果。
分析结果——将实际结果与预期结果进行比较。对于失败的测试，确定问题出在代理代码、支持逻辑还是测试规范本身。
迭代——根据需要修复代理代码或测试规范，重新部署并重新运行，直到达到覆盖目标。

Reference Files

参考文件

CLI for Agents — exact command syntax for test create, test run, test results
Core Language — agent structure for designing meaningful tests
Design & Agent Spec — Agent Spec as test coverage baseline
testing-agentforce skill — test spec YAML format, expectations, metrics, test design methodology, and test spec template

代理CLI指南——测试创建、测试运行、测试结果的准确命令语法
核心语言——代理结构，用于设计有意义的测试
设计与Agent Spec——作为测试覆盖基准的Agent Spec
testing-agentforce技能——测试规范YAML格式、预期结果、指标、测试设计方法和测试规范模板

The Agent Spec

Agent Spec

Agent Spec is the central artifact this skill produces and consumes. A structured design document representing agent's purpose, topic graph, actions with backing logic, variables, gating logic, and behavioral intent.

Agent Specs evolve with the agent. Sparse during agent creation (purpose, topics, directional notes). Fleshed out during agent build (flowchart, backing logic mapped, gating documented). Reverse-engineered when comprehending existing agents. Critical for advanced troubleshooting, providing reference to compare expected vs. actual behavior. During testing, test coverage maps against it.

Always produce or update Agent Spec as first step of any operation that changes or analyzes agent. It is consistent grounding to work from, and a durable artifact a developer can review.

Read Design & Agent Spec for Agent Spec structure and production methodology.

Agent Spec是本技能生成和使用的核心工件。它是一份结构化设计文档，代表了代理的用途、主题图、带支持逻辑的动作、变量、门控逻辑和行为意图。

Agent Spec会随代理一起演进。在代理创建阶段较为简略（用途、主题、方向性说明），在代理构建阶段逐渐完善（流程图、映射的支持逻辑、记录的门控规则）。在理解现有代理时会进行反向工程。对于高级故障排除至关重要，可作为比较预期与实际行为的参考。在测试阶段，测试覆盖范围会与之对应。

任何更改或分析代理的操作，第一步都应生成或更新Agent Spec。它是工作的一致基础，也是开发人员可查阅的持久工件。

有关Agent Spec的结构和生成方法，请阅读设计与Agent Spec。

Assets

资源

The

assets/

directory contains templates and examples. Read when you need a starting point or a concrete reference for artifacts and source files.

assets/agent-spec-template.md
— Agent Spec template with all sections and placeholder content. Copy to
```
<AgentName>-AgentSpec.md
```
in project directory, then fill in during design. Save Agent Spec as file — significant design artifact that benefits from proper rendering, especially Mermaid Topic Map diagram.
assets/local-info-agent-annotated.agent
— Complete annotated example based on Local Info Agent, showing all major Agent Script constructs in context with inline comments explaining why each construct is used. Read when you need concrete reference for how concepts compose into working agent, or as fallback when focused examples in reference files aren't sufficient.
assets/template-single-topic.agent
— Minimal agent with one topic. Copy and modify for simple agents.
assets/template-multi-topic.agent
— Minimal agent with multiple topics and transitions. Copy and modify for complex agents.
assets/invocable-apex-template.cls
— Reference for invocable Apex classes. Copy and modify when complex Apex backing logic is desired.

assets/

目录包含模板和示例。当您需要起点或工件和源代码的具体参考时，请查阅。

assets/agent-spec-template.md
——包含所有章节和占位符内容的Agent Spec模板。复制到项目目录的
```
<AgentName>-AgentSpec.md
```
中，然后在设计过程中填写内容。将Agent Spec保存为文件——这是重要的设计工件，尤其是Mermaid主题图，需要正确渲染才能发挥最大作用。
assets/local-info-agent-annotated.agent
——基于Local Info Agent的完整带注释示例，展示了所有主要Agent Script结构的上下文用法，并附有内联注释解释使用每个结构的原因。当您需要具体参考了解概念如何组合成可用代理，或参考文件中的聚焦示例不够用时，请查阅此文件。
assets/template-single-topic.agent
——仅包含一个主题的最小代理。复制并修改可用于简单代理。
assets/template-multi-topic.agent
——包含多个主题和转换的最小代理。复制并修改可用于复杂代理。
assets/invocable-apex-template.cls
——可调用Apex类的参考模板。当需要复杂Apex支持逻辑时，复制并修改此模板。

Important Constraints

重要约束

Use only Salesforce CLI and Salesforce org. Do not reference or depend on other skills, MCP servers, or external tooling. All commands use
```
sf
```
(Salesforce CLI).
Only certain backing logic types are valid for actions. For example, only invocable Apex (not arbitrary Apex classes) can back action. Similar constraints may apply to Flows and Prompt Templates. When wiring actions to backing logic, consult Design & Agent Spec reference file for valid types and stubbing methodology.
sf agent generate test-spec
is not for agentic use. It is interactive, REPL-style command designed for humans. When creating test specs, start from boilerplate template in assets instead.

仅使用Salesforce CLI和Salesforce组织。请勿引用或依赖其他技能、MCP服务器或外部工具。所有命令均使用
```
sf
```
（Salesforce CLI）。
仅特定类型的支持逻辑可用于动作。例如，只有可调用Apex（而非任意Apex类）可作为动作的支持逻辑。Flow和Prompt Template也可能有类似的约束。将动作连接到支持逻辑时，请查阅设计与Agent Spec参考文件了解有效类型和存根方法。
sf agent generate test-spec
不适用于自动化使用。这是为人类设计的交互式REPL风格命令。创建测试规范时，请从资源中的样板模板开始。

Common Issues Quick Reference

常见问题快速参考

Internal Error, try again later
during publish: Invalid or missing

default_agent_user

. Re-run query from Design & Agent Spec, Section 3. Do not invent username.

Unable to access Salesforce Agent APIs...
during preview:

default_agent_user

lacks permissions. See Agent User Setup & Permissions. Do NOT publish as fix —

--use-live-actions

does not require published agent.

Permission error referencing different username than configured: Same fix as above — error references org's default running user, but root cause is Einstein Agent User permissions.

Agent fails with permission error even though current topic's actions work: Planner validates ALL actions across ALL topics at startup. One missing permission fails entire agent.

Apex action returns empty results in live preview but works in simulated:

WITH USER_MODE

+ missing object permissions = silent failure (0 rows, no error). See Agent User Setup & Permissions, Section 6.2.

发布时出现
Internal Error, try again later
：

default_agent_user

无效或缺失。重新运行设计与Agent Spec第3节中的查询。请勿自行编造用户名。

预览时出现
Unable to access Salesforce Agent APIs...
：

default_agent_user

缺少权限。请参阅代理用户设置与权限。请勿通过发布来修复——

--use-live-actions

不需要已发布的代理。

权限错误引用的用户名与配置的不同： 修复方法同上——错误引用的是组织的默认运行用户，但根本原因是Einstein Agent User权限不足。

即使当前主题的动作可用，代理仍因权限错误失败： 规划器在启动时会验证所有主题的所有动作。一个权限缺失会导致整个代理失败。

Apex动作在实时预览中返回空结果，但在模拟中正常工作：

WITH USER_MODE

+ 对象权限缺失 = 静默失败（0行，无错误）。请参阅代理用户设置与权限第6.2节。

Syntax Quick Reference

语法快速参考

Block order:

system:

→

config:

→

variables:

→

connection:

→

knowledge:

→

language:

→

start_agent topic_selector:

→

topic:

blocks

Indentation: 4 spaces per indent level. Never use tabs. Mixing spaces and tabs breaks the parser.
Booleans:
```
True
```
/
```
False
```
(capitalized)
Strings: always double-quoted
Numeric action I/O: bare
```
number
```
works for variables but fails at publish in action I/O. Use
```
object
```
+
```
complex_data_type_name
```
for numeric action parameters. See Complex Data Types for the full decision tree.
```
after_reasoning:
```
has NO
```
instructions:
```
wrapper
No
```
else if
```
— use compound
```
if x and y:
```
or sequential flat ifs
Reserved
```
@InvocableVariable
```
names:
```
model
```
,
```
description
```
,
```
label
```
— cannot be used as Apex parameter names
```
@inputs
```
and
```
@outputs
```
are ephemeral:
```
@inputs
```
only in
```
with
```
;
```
@outputs
```
only in
```
set
```
/
```
if
```
immediately after the action.
```
@inputs
```
in
```
set
```
= silent failure.

See Complex Data Types for the full Lightning type mapping decision tree. See Instruction Resolution for the 3-phase runtime model.

块顺序：

system:

→

config:

→

variables:

→

connection:

→

knowledge:

→

language:

→

start_agent topic_selector:

→

topic:

块

缩进：每个缩进级别4个空格。请勿使用制表符。混合使用空格和制表符会导致解析器出错。
布尔值：
```
True
```
/
```
False
```
（首字母大写）
字符串：始终使用双引号
数值动作输入输出：变量使用裸
```
number
```
有效，但在动作输入输出中发布时会失败。对于数值动作参数，请使用
```
object
```
+
```
complex_data_type_name
```
。完整的决策树请参阅复杂数据类型。
```
after_reasoning:
```
没有
```
instructions:
```
包装器
没有
```
else if
```
——使用复合
```
if x and y:
```
或连续的扁平if语句
保留的
```
@InvocableVariable
```
名称：
```
model
```
、
```
description
```
、
```
label
```
——不能用作Apex参数名称
```
@inputs
```
和
```
@outputs
```
是临时的：
```
@inputs
```
仅在
```
with
```
中可用；
```
@outputs
```
仅在动作完成后的
```
set
```
/
```
if
```
中可用。在
```
set
```
中使用
```
@inputs
```
会导致静默失败。

完整的Lightning类型映射决策树请参阅复杂数据类型。3阶段运行时模型请参阅指令解析。

Architecture Patterns

架构模式

Three primary FSM patterns. Full details with code in Architecture Patterns.

Hub-and-Spoke (most common):
```
start_agent
```
routes to specialized topics. Each topic has "back to hub" transition. Do NOT create a separate routing topic.
Verification Gate: Identity verification before protected topics.
```
available when
```
guards on protected transitions.
Post-Action Loop: Post-action checks at TOP of
```
instructions: ->
```
trigger on re-resolution after action completes.

三种主要的有限状态机（FSM）模式。包含代码的完整详细信息请参阅架构模式。

中心辐射型（最常见）：
```
start_agent
```
路由到专用主题。每个主题都有“返回中心”的转换。请勿创建单独的路由主题。
验证门控：访问受保护主题前进行身份验证。受保护转换使用
```
available when
```
守卫。
动作后循环：
```
instructions: ->
```
顶部的动作后检查会在动作完成后的重新解析时触发。

Scoring Rubric

评分标准

Score every generated agent on 100 points across 7 categories: Structure (15), Safety (15), Deterministic Logic (20), Instruction Resolution (20), FSM Architecture (10), Action Configuration (10), Deployment Readiness (10).

See Scoring Rubric for the complete rubric.

从7个类别对每个生成的代理进行100分制评分：结构（15分）、安全性（15分）、确定性逻辑（20分）、指令解析（20分）、FSM架构（10分）、动作配置（10分）、部署就绪性（10分）。

完整的评分标准请参阅评分标准。

Review Mode

审核模式

When user provides an existing

.agent

file (e.g.,

review path/to/file.agent

Read the file
Score against the 100-point rubric
List every issue grouped by category
Provide corrected code snippets
Offer to apply fixes

当用户提供现有

.agent

文件时（例如

review path/to/file.agent

）：

读取文件
根据100分制评分标准进行评分
按类别列出所有问题
提供修正后的代码片段
提出修复建议

Safety Review

安全审核

7-category LLM-driven safety review for

.agent

files. Integrated into Phase 0 of authoring and deployment. Categories: Identity & Transparency, User Safety, Data Handling, Content Safety, Fairness, Deception, Scope & Boundaries.

See Safety Review for the complete framework, severity levels, false positive guidance, and adversarial test prompts.

针对

.agent

文件的7类LLM驱动安全审核，集成到创作和部署的第0阶段。类别：身份与透明度、用户安全、数据处理、内容安全、公平性、欺骗性、范围与边界。

完整的框架、严重级别、误报指南和对抗性测试提示请参阅安全审核。

Discover & Scaffold

发现与脚手架

Validate action targets exist in org and generate stubs for missing ones.

See Discover Reference and Scaffold Reference.

CRITICAL: Stubs must return realistic data, not

'TODO'

. Placeholder responses cause SMALL_TALK grounding because the LLM falls back to training data.

验证动作目标在组织中是否存在，并为缺失的目标生成存根。

请参阅发现参考和脚手架参考。

重要提示： 存根必须返回真实数据，而非

'TODO'

。占位符响应会导致SMALL_TALK问题，因为LLM会回退到训练数据。

Deploy Lifecycle

部署生命周期

Validate → deploy metadata → publish bundle → activate. See Deploy Reference for phases, error recovery, CI/CD, and rollback.

验证 → 部署元数据 → 发布包 → 激活。阶段、错误恢复、CI/CD和回滚请参阅部署参考。

Template Assets

模板资源

Ready-to-use

.agent

templates in

assets/agents/

(hello-world, simple-qa, multi-topic, production-faq, order-service, verification-gate). See also

assets/patterns/

for 11+ reusable design patterns and Examples for inline walkthroughs.

assets/agents/

中包含即用型

.agent

模板（hello-world、simple-qa、multi-topic、production-faq、order-service、verification-gate）。另请参阅

assets/patterns/

中的11+个可重用设计模式，以及示例中的分步指南。

Additional References

附加参考

Topic	File
Architecture patterns	architecture-patterns.md
Type mapping decision tree	complex-data-types.md
Feature validity by context	feature-validity.md
Instruction resolution model	instruction-resolution.md
Complete agent examples	examples.md

主题	文件
架构模式	architecture-patterns.md
类型映射决策树	complex-data-types.md
上下文特征有效性	feature-validity.md
指令解析模型	instruction-resolution.md
完整代理示例	examples.md