| name | sf-ai-agentscript |
| description | Agent Script DSL for deterministic Agentforce agents. TRIGGER when: user writes or edits .agent files, builds FSM-based agents, uses Agent Script CLI (sf agent generate authoring-bundle, sf agent validate authoring-bundle, sf agent preview, sf agent publish authoring-bundle, sf agent activate), or asks about deterministic agent patterns, slot filling, or instruction resolution. DO NOT TRIGGER when: Builder metadata work (use sf-ai-agentforce), agent testing (use sf-ai-agentforce-testing), or persona design (use sf-ai-agentforce-persona).
|
| license | MIT |
| compatibility | Requires Agentforce license and API v66.0+; Einstein Agent User is required for Service Agents only |
| metadata | {"version":"2.9.0","author":"Jag Valaiyapathy","scoring":"100 points across 6 categories","validated":"0-shot generation tested against multiple representative sample agents. Agent user setup validated against representative Service Agent and Employee Agent scenarios.","last_validated":"2026-03-20","validation_status":"PASS","validation_agents":"24","validate_by":"2026-04-10"} |
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.
Right-Size Determinism
- Determinism is a dial, not a destination.
- Use Agent Script when “mostly right” is not acceptable: gates, mandatory sequencing, explicit state transitions, compliance, or drift control.
- If a workflow is fully static and linear, use Flow or Apex instead of scripting the conversation.
- Prefer a deterministic envelope: deterministic entry/gate → flexible middle → deterministic closeout.
- More determinism is not automatically better. Start minimal, then harden only the parts that show routing drift, sequencing failures, or compliance risk.
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
sf agent activate --api-name MyAgent -o TARGET_ORG
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
