Salesforce AI Agent Script

---

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:

maintaining Builder metadata agents (GenAiFunction, GenAiPlugin, GenAiPromptTemplate, Models API, custom Lightning types) → sf-ai-agentforce

designing persona / tone / voice → sf-ai-agentforce-persona

building formal test plans or coverage loops → sf-ai-agentforce-testing

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:

1. Exactly one start_agent block 2. No mixed tabs and spaces 3. Booleans are True / False 4. No else if and no nested if 5. No top-level actions: block 6. No @inputs in set expressions 7. linked variables have no defaults 8. linked variables do not use object / list types 9. Use explicit agent_type 10. Use @actions. prefixes consistently 11. Use run @actions.X only when X is a topic-level action definition with target: 12. Do not branch directly on raw @system_variables.user_input contains/startswith/endswith for intent routing 13. On prompt-template outputs, prefer is_displayable: False + is_used_by_planner: True 14. 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  -o TARGET_ORG --json

Publishing does not activate the agent. For automation, prefer --version --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

references/activation-checklist.md

references/syntax-reference.md

references/actions-reference.md

Publish / runtime safety

references/agent-user-setup.md

references/production-gotchas.md

references/customer-web-client.md

references/known-issues.md

Architecture / reasoning

references/architecture-patterns.md

references/instruction-resolution.md

references/fsm-architecture.md

references/patterns-quick-ref.md

Validation / testing / debugging

references/preview-test-loop.md

references/testing-guide.md

references/debugging-guide.md

references/validator-rule-catalog.md

Examples / scaffolds

references/minimal-examples.md

references/migration-guide.md

assets/

assets/agents/

assets/patterns/

Project documentation

references/version-history.md

references/sources.md

---

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

Agent Script Documentation

Agent Script Recipes

Agentforce DX Guide

references/official-sources.md