Sf AI Agentscript

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.

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:

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

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

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.