SF-AI-AgentScript Skill
Agent Script is the code-first path for deterministic Agentforce agents. Use this skill when the user is authoring .agent files, building finite-state topic flows, or needs repeatable control over routing, variables, actions, and publish behavior.
Start with the shortest guide first: references/activation-checklist.md
Migrating from the Builder UI? Use references/migration-guide.md
When This Skill Owns the Task
Use sf-ai-agentscript when the work involves:
- creating or editing
.agent files
- deterministic topic routing, guards, and transitions
- Agent Script CLI workflows (
sf agent generate authoring-bundle, sf agent validate authoring-bundle, sf agent preview, sf agent publish authoring-bundle, sf agent activate)
- slot filling, instruction resolution, post-action loops, or FSM design
Delegate elsewhere when the user is:
If the user is in Builder Script / Canvas view but the outcome is a .agent authoring bundle, keep the work in sf-ai-agentscript.
Required Context to Gather First
Ask for or infer:
- agent purpose and whether Agent Script is truly the right fit
- Service Agent vs Employee Agent
- target org and publish intent
- expected actions / targets (Flow, Apex, PromptTemplate, etc.)
- whether the request is authoring, validation, preview, or publish troubleshooting
Activation Checklist
Before you author or fix any .agent file, verify these first:
- Exactly one
start_agent block
- No mixed tabs and spaces
- Booleans are
True / False
- No
else if and no nested if
- No top-level
actions: block
- No
@inputs in set expressions
linked variables have no defaultslinked variables do not use object / list types- Use explicit
agent_type
- Use
@actions. prefixes consistently
- Use
run @actions.X only when X is a topic-level action definition with target:
- Do not branch directly on raw
@system_variables.user_input contains/startswith/endswith for intent routing
- On prompt-template outputs, prefer
is_displayable: False + is_used_by_planner: True
- Do not assume
@outputs.X is scalar — inspect the output schema before branching or assignment
For the expanded version, use references/activation-checklist.md.
Non-Negotiable Rules
1) Service Agent vs Employee Agent
| Agent type | Required | Forbidden / caution |
|---|
AgentforceServiceAgent | Valid default_agent_user, correct permissions, target-org checks, prefer sf org create agent-user | Publishing without a real Einstein Agent User |
AgentforceEmployeeAgent | Explicit agent_type | Supplying default_agent_user |
Full details: references/agent-user-setup.md
2) Recommended top-level block convention
Use this order for consistency in this skill's examples and reviews:
config:
variables:
system:
connection:
knowledge:
language:
start_agent:
topic:
Official Salesforce materials present top-level blocks in differing sequences, and local validation evidence indicates multiple orderings compile. Treat this as a style convention, not a standalone correctness or publish blocker.
3) Critical config fields
| Field | Rule |
|---|
developer_name | Must match folder / bundle name |
description | Public docs/examples should use this config field |
agent_type | Set explicitly every time |
default_agent_user | Service Agents only |
Local tooling also accepts agent_description: for compatibility, but this skill's public docs and examples should prefer description:.
4) Syntax blockers you should treat as immediate failures
else if- nested
if
- comment-only
if bodies
- top-level
actions:
- invocation-level
inputs: / outputs: blocks
- reserved variable / field names like
description and label
Canonical rule set: references/syntax-reference.md and references/validator-rule-catalog.md
Recommended Workflow
Recommended Authoring Workflow
Phase 1 — design the agent
- decide whether the problem is actually deterministic enough for Agent Script
- model topics as states and transitions as edges
- define only the variables you truly need
Phase 2 — author the .agent
- create
config, system, start_agent, and topics first
- add target-backed actions with full
inputs: and outputs:
- use
available when for deterministic tool visibility
- normalize raw intent/validation signals into booleans or enums before branching; avoid direct substring checks on raw user utterances for critical control flow
- keep post-action checks at the top of
instructions: ->
Default authoring stance
- Default to direct
.agent authoring and edits in source control.
- Use
sf agent generate authoring-bundle --no-spec only when the user wants local bundle scaffolding.
- Treat
sf agent generate agent-spec as optional ideation / topic bootstrap, not the default workflow.
- Do not route Agent Script users toward
sf agent create or sf agent generate template.
Phase 3 — validate continuously
Validation already runs automatically on write/edit. Use the CLI before publish:
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json
The validator covers structure, runtime gotchas, target readiness, and org-aware Service Agent checks. Rule IDs live in references/validator-rule-catalog.md.
Phase 4 — preview smoke test
Use the preview loop before publish:
- derive 3–5 smoke utterances
- start preview with the
start / send / end subcommands, not bare sf agent preview
- if you use
--authoring-bundle, always choose a mode explicitly: --simulate-actions or --use-live-actions
- inspect topic routing / action invocation / safety / grounding
- fix and rerun up to 3 times
Full loop: references/preview-test-loop.md
Phase 5 — publish and activate
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json
# Manual activation
sf agent activate --api-name MyAgent -o TARGET_ORG
# CI / deterministic activation of a known BotVersion
sf agent activate --api-name MyAgent --version <n> -o TARGET_ORG --json
Publishing does not activate the agent.
For automation, prefer --version <n> --json so activation is deterministic and machine-readable.
Deterministic Building Blocks
These execute as code, not suggestions:
- conditionals
available when guards- variable checks
- direct
set / transition to
run @actions.X only when X is a topic-level action definition with target:- variable injection into LLM-facing text
Important distinction:
- Deterministic:
set, transition to, and run @actions.X for a target-backed topic action
- LLM-directed:
reasoning.actions: utilities / delegations such as @utils.setVariables, @utils.transition, and {!@actions.X} instruction references
If you need deterministic behavior for something that is currently modeled as a reasoning-level utility, either:
- rewrite it as direct
set / transition to, or
- promote it to a topic-level target-backed action and
run that action
See references/instruction-resolution.md and references/architecture-patterns.md.
Cross-Skill Integration
Cross-Skill Orchestration
| Task | Delegate to | Why |
|---|
Build flow:// targets | sf-flow | Flow creation / validation |
| Build Apex action targets | sf-apex | @InvocableMethod and business logic |
| Test topic routing / actions | sf-ai-agentforce-testing | Formal test specs and fix loops |
| Deploy / publish | sf-deploy | Deployment orchestration |
High-Signal Failure Patterns
| Symptom | Likely cause | Read next |
|---|
Internal Error during publish | invalid Service Agent user or missing action I/O | references/agent-user-setup.md, references/actions-reference.md |
invalid input/output parameters on prompt template action | Target template is in Draft status — activate it first | references/action-prompt-templates.md |
| Parser rejects conditionals | else if, nested if, empty if body | references/syntax-reference.md |
| Action target issues | missing Flow / Apex target, inactive Flow, bad schemas | references/actions-reference.md |
| Prompt template runs but user sees blank response | prompt output marked is_displayable: True | references/production-gotchas.md, references/action-prompt-templates.md |
| Prompt action runs but planner behaves like output is missing | output hidden from direct display but not planner-visible | references/production-gotchas.md, references/actions-reference.md |
ACTION_NOT_IN_SCOPE on run @actions.X | run points at a utility / delegation / unresolved action instead of a topic-level target-backed definition | references/syntax-reference.md, references/instruction-resolution.md |
| Deterministic cancel / revise / URL checks behave inconsistently | raw @system_variables.user_input matching or string-method guards are being used as control-flow-critical validation | references/syntax-reference.md, references/production-gotchas.md |
@outputs.X comparisons or assignments behave unexpectedly | the action output is structured/wrapped, not a plain scalar | references/actions-reference.md, references/syntax-reference.md |
| Preview and runtime disagree | linked vars / context / known platform issues | references/known-issues.md |
| Validate passes but publish fails | org-specific user / permission / retrieve-back issue | references/production-gotchas.md, references/cli-guide.md |
Reference Map
Start here
Publish / runtime safety
Architecture / reasoning
Validation / testing / debugging
Examples / scaffolds
Project documentation
Score Guide
| Score | Meaning |
|---|
| 90+ | Deploy with confidence |
| 75–89 | Good, review warnings |
| 60–74 | Needs focused revision |
| < 60 | Block publish |
Full rubric: references/scoring-rubric.md
Official Resources
