agentforce-generate

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 actions, instructions, subagents, flow control, and configuration; and a

bundle-meta.xml

file containing bundle metadata. Agents process utterances by routing through subagents, 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 Agent。2025年推出时，未在任何AI模型中使用训练数据。编写、修改、诊断或部署Agent Script Agent所需的所有内容都包含在本技能的参考文件中。

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

Agent Script Agent由

AiAuthoringBundle

元数据定义——这是一个目录，包含一个.agent文件（内含描述动作、指令、子Agent、流程控制和配置的Agent Script源代码），以及一个

bundle-meta.xml

文件（包含包元数据）。Agent通过子Agent路由处理用户输入，每个子Agent的指令和动作由Apex、Flows、Prompt Template及其他类型的底层逻辑提供支持。

本技能涵盖Agent Script的完整生命周期：Agent设计、编写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 subagent 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>
```
进行设置。
先诊断再修复。验证或调试Agent行为时，务必使用
--use-live-actions
参数预览创作包。发送用户输入，然后读取生成的会话跟踪信息，以明确了解Agent的行为。跟踪文件会显示子Agent选择、动作输入输出以及LLM推理逻辑。未进行此步骤前，请勿修改.agent文件或底层逻辑。有关跟踪文件位置和诊断模式，请参阅验证与调试。
规格书审批是硬性门槛。在Agent规格书创建完成后，必须获得用户明确批准才能继续后续工作。

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

创建Agent

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

用户希望从零开始构建新Agent。务必使用Agent Script。与用户协作，用非Salesforce专属术语的通俗语言明确Agent的用途、子Agent和动作。

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 subagent 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 subagent
- Traces confirm correct subagent 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.

阅读Agent专用CLI获取精确命令语法。

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

生成创作包 —

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规格书中的可调用模式替换类主体。务必部署：
```
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路由、门控和动作调用与Agent规格书一致。若行为不符，切换到诊断行为问题工作流。修复问题后再返回。 检查点 — 满足以下所有条件才能继续发布：
- ```
validate authoring-bundle
```
  零错误通过
- 使用代表性输入对每个子Agent进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认子Agent路由和动作调用正确
- 用户明确批准部署
发布 — 发布仅验证元数据结构，不验证Agent行为。每次发布都会生成永久版本号。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
若发布失败，在重试前遵循元数据与生命周期第5节中的故障排除清单。

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

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

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

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 — subagent graph design, flow control patterns, Agent Spec production, backing logic analysis; Section 3 for environment prerequisites
Subagent Map Diagrams — Mermaid diagram conventions for visualizing the agent's subagent graph
Agent User Setup & Permissions — permission set assignment, object permissions, cross-subagent 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

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

Comprehend an Existing Agent

理解现有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 Agent。可能指向

AiAuthoringBundle

目录，或询问“这个Agent有什么用？”或“我需要修复这个Agent，但不懂它的工作原理。”

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 Subagent Map diagram — Read Subagent Map Diagrams for Mermaid conventions. Generate flowchart of subagent 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 subagent relationships.
Present to user — Share Agent Spec, Subagent Map, and annotated source if produced. Check Anti-Patterns section in Core Language reference and flag any matches found in code.

定位Agent — 读取
```
sfdx-project.json
```
识别包目录，在其中找到
```
AiAuthoringBundle
```
目录，读取.agent文件和
```
bundle-meta.xml
```
文件。
阅读代码 — 阅读核心语言了解语法和执行模型，然后再解析.agent文件。
映射底层逻辑 — 针对每个带有
```
target
```
的动作，在项目中找到底层实现（Apex类、Flow、Prompt Template），记录输入输出契约。
逆向工程Agent规格书 — 阅读设计与Agent规格书了解Agent规格书结构，根据代码生成Agent规格书并保存为文件。
生成子Agent映射图 — 阅读子Agent映射图了解Mermaid约定，生成显示子Agent图的流程图，展示过渡、门控和动作关联。
注释源代码 — 询问用户是否需要为Agent Script源代码添加解释注释。若请求，在.agent文件中添加内联注释，解释流程控制决策、门控依据和子Agent关系。
提交给用户 — 分享生成的Agent规格书、子Agent映射图（若有）和带注释的源代码。检查核心语言参考中的反模式部分，标记代码中发现的匹配项。

Reference Files

参考文件

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

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

Modify an Existing Agent

修改现有Agent

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

用户希望在现有Agent中添加、移除或更改子Agent、动作、指令或流程控制。可能用通俗语言描述更改（如“添加计费子Agent”），或引用特定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 subagent
- Traces confirm correct subagent 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

阅读Agent专用CLI获取精确命令语法。

理解现有Agent — 若没有Agent规格书，先遵循“理解现有Agent”工作流进行逆向工程。
更新Agent规格书 — 阅读设计与Agent规格书了解流程控制模式和底层逻辑分析。修改Agent规格书以反映预期更改。对于新动作，务必询问是否需要扫描现有底层逻辑。除非另有指示，否则通过读取
```
sfdx-project.json
```
识别包目录，然后在每个目录中搜索
```
classes/
```
中的
```
@InvocableMethod
```
、
```
flows/
```
中的
```
AutoLaunchedFlow
```
以及
```
promptTemplates/
```
中的模板元数据。标记匹配项为
```
EXISTS
```
；未匹配的动作为
```
NEEDS STUB
```
。务必将更新后的Agent规格书保存为文件。
等待用户审批更新后的Agent规格书。将规格书提交给用户，请求审批或反馈。未获得批准前不得继续。批准后，除非步骤失败，否则无需停顿继续执行。
编辑代码 — 阅读核心语言了解语法和反模式。编辑.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规格书中的可调用模式替换类主体。务必部署：
```
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
```
  零错误通过
- 使用代表性输入对每个子Agent进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认子Agent路由和动作调用正确
- 用户明确批准部署
发布 — 发布仅验证元数据结构，不验证Agent行为。每次发布都会生成永久版本号。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
若发布失败，在重试前遵循元数据与生命周期第5节中的故障排除清单。

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

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

验证已发布Agent — 激活后，使用以下命令预览面向用户的行为：
```
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

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

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.

阅读Agent专用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。

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

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

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

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 subagent" or "the action isn't being called." Fundamentally different from

validate

preview start

errors — code is valid but behavior is wrong.

Agent编译通过，预览可以启动并使用

--use-live-actions

，但Agent行为不符合预期。用户描述的症状如“Agent总是路由到错误的子Agent”或“动作未被调用”。这与

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: subagent 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 subagent with
```
sf agent preview send
```
. One message is not enough — confirm behavior per subagent before proceeding.
Analyze session traces — Examine trace output to confirm subagent 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.

阅读Agent专用CLI获取精确命令语法。

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

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规格书 — 作为行为基准的Agent规格书、门控模式
验证与调试 — 预览工作流、会话跟踪分析
已知问题 — 仅在代码逻辑正确但行为异常时查阅

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.

用户希望将可用Agent从本地开发环境部署到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 subagent
- Traces confirm correct subagent 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.

阅读Agent专用CLI获取精确命令语法。

验证编译 —

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

验证失败则不得继续。

部署包和依赖项 — 阅读元数据与生命周期了解依赖管理和部署命令，将
```
AiAuthoringBundle
```
及其所有底层逻辑（Apex类、Flows、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>"
```
测试关键对话路径，验证Agent在实时动作支持下的行为。 检查点 — 满足以下所有条件才能继续发布：
- ```
validate authoring-bundle
```
  零错误通过
- 使用代表性输入对每个子Agent进行了实时预览（
```
--use-live-actions
```
  ）测试
- 跟踪信息确认子Agent路由和动作调用正确
- 用户明确批准部署
发布 — 发布仅验证元数据结构，不验证Agent行为。不要在开发/测试内部循环中发布。仅在激活Agent并向终端用户公开前作为最后一步发布。
```
sf agent publish authoring-bundle --json --api-name <Developer_Name>
```
若发布失败，在重试前遵循元数据与生命周期中的发布故障排除部分。

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

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

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

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

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

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.

用户的Agent已发布并激活，但出现预览阶段未发现的问题。包括信用过度消耗、令牌或大小限制失败、循环护栏中断、保留关键字运行时错误、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.

阅读Agent专用CLI获取精确命令语法。

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

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解决方法
Agent专用CLI — 预览、发布、激活的命令语法
验证与调试 — 预览工作流、会话跟踪分析
已知问题 — 仅在问题可能是平台Bug时查阅

Delete or Rename an Agent

删除或重命名Agent

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

AiAuthoringBundle

versioning and published version dependencies.

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

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.

阅读Agent专用CLI获取精确命令语法。

了解当前状态 — 阅读元数据与生命周期了解版本控制、删除机制和重命名机制，确定Agent是否已发布、存在多少版本以及当前是否处于激活状态。
若激活则停用 —
```
sf agent deactivate --json --api-name <Developer_Name>
```
激活状态的Agent无法删除或重命名。
执行操作 — 删除操作：遵循元数据与生命周期参考中的删除机制；重命名操作：遵循同一参考中的重命名机制。
清理孤立元数据 — 检查并移除孤立元数据：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

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

Test an Agent

测试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 Agent创建自动化测试。涉及编写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 subagent, 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 agentforce-test skill. That skill owns all testing content. For each coverage target, write one or more test scenarios: user utterance, expected subagent 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 agentforce-test 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.

阅读Agent专用CLI获取精确命令语法。

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

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
agentforce-test skill — test spec YAML format, expectations, metrics, test design methodology, and test spec template

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

The Agent Spec

Agent规格书

Agent Spec is the central artifact this skill produces and consumes. A structured design document representing agent's purpose, subagent 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规格书是本技能生成和使用的核心工件。它是一份结构化设计文档，代表Agent的用途、子Agent图、带底层逻辑的动作、变量、门控逻辑和行为意图。

Agent规格书随Agent一起演进。Agent创建初期内容简略（用途、主题、方向性说明）；Agent构建过程中逐步完善（流程图、映射的底层逻辑、记录的门控规则）；理解现有Agent时进行逆向工程；在高级故障排除中至关重要，提供预期行为与实际行为对比的参考；测试时，测试覆盖范围与之对应。

任何更改或分析Agent的操作，第一步都必须生成或更新Agent规格书。它是工作的一致基准，也是开发人员可查阅的持久工件。

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

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 Subagent 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-subagent.agent
— Minimal agent with one subagent. Copy and modify for simple agents.
assets/template-multi-subagent.agent
— Minimal agent with multiple subagents 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规格书模板，包含所有章节和占位符内容。复制到项目目录的
```
<AgentName>-AgentSpec.md
```
，然后在设计过程中填写内容。务必将Agent规格书保存为文件——这是重要的设计工件，尤其是Mermaid子Agent映射图，需要正确渲染。
assets/local-info-agent-annotated.agent
— 基于Local Info Agent的完整带注释示例，展示了所有主要Agent Script构造的上下文，并带有内联注释解释使用每个构造的原因。当需要了解概念如何组合成可用Agent的具体参考，或参考文件中的聚焦示例不足时，请查阅。
assets/template-single-subagent.agent
— 包含单个子Agent的最小Agent模板。复制并修改以创建简单Agent。
assets/template-multi-subagent.agent
— 包含多个子Agent和过渡的最小Agent模板。复制并修改以创建复杂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类）可为动作提供支持。Flows和Prompt Template也可能有类似约束。将动作与底层逻辑关联时，请查阅设计与Agent规格书参考文件了解有效类型和存根方法。
sf agent generate test-spec
不适合Agent自动化使用。这是为人类设计的交互式REPL风格命令。创建测试规格时，请从assets中的样板模板开始。

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 subagent's actions work: Planner validates ALL actions across ALL subagents 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规格书第3节中的查询。请勿自行编造用户名。

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

default_agent_user

缺少权限。请参阅Agent用户设置与权限。不要通过发布来修复——

--use-live-actions

不需要已发布的Agent。

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

当前子Agent的动作可用，但Agent仍因权限错误失败： 规划器在启动时会验证所有子Agent的所有动作。一项权限缺失会导致整个Agent失败。

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

WITH USER_MODE

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

Syntax Quick Reference

语法快速参考

Block order:

system:

→

config:

→

variables:

→

connection:

→

knowledge:

→

language:

→

start_agent agent_router:

→

subagent:

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 agent_router:

→

subagent:

块

缩进：每个缩进级别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 subagents. Each subagent has "back to hub" transition. Do NOT create a separate routing subagent.
Verification Gate: Identity verification before protected subagents.
```
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
```
路由到专用子Agent，每个子Agent都有“返回中心”的过渡。不要创建单独的路由子Agent。
验证门控：访问受保护子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个维度对生成的Agent进行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-subagent, 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-subagent、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
完整Agent示例	examples.md