SF-AI-AgentScript Skill

“Prompt engineering is like writing laws in poetry – beautiful, but not enforceable.”

Agent Script transforms agent development from prompt-based suggestions to code-enforced guarantees. This skill guides you through writing, debugging, testing, and deploying Agentforce agents using the Agent Script DSL.

⚠️ CRITICAL WARNINGS

API & Version Requirements

MANDATORY Pre-Deployment Checks

1. default_agent_user MUST be valid – Query: SELECT Username FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true
2. No mixed tabs/spaces – Use consistent indentation (2-space, 3-space, or tabs – never mix)
3. Booleans are capitalized – Use True/False, not true/false
4. Exactly one start_agent block – Multiple entry points cause compilation failure

⛔ SYNTAX CONSTRAINTS (Validated via Testing + Official Spec)

🔴 Reserved Field Names (Breaking in Recent Releases)

Common field names that cause parse errors when used as variable or I/O field names:

❌ RESERVED as variable/field names:
description, label, is_required, is_displayable, is_used_by_planner

✅ WORKAROUNDS for variable/field names:
description  → descriptions, description_text, desc_field
label        → label_text, display_label, label_field

Important distinction: is_required, is_displayable, is_used_by_planner, and label are reserved as variable/field names but are valid as action I/O metadata properties. For example, you cannot name a variable label, but you CAN use label: as a property on an action definition, input, or output. See references/feature-validity.md.

Feature Validity, Data Types & UI Bugs

See references/feature-validity.md for the full feature validity by context table (which properties work on @utils.transition vs target-backed actions).

See references/complex-data-types.md for the complex_data_type_name mapping table and Agent Script → Lightning type mapping.

Canvas View can silently corrupt syntax (== → {! OPERATOR.EQUAL }, missing colons, de-indentation). Always use Script view for structural edits. Preview Mode has known bugs with linked variables and output property access — see references/known-issues.md for workarounds.

Conditional nesting: else if is NOT valid, nested if inside if/else: is NOT valid (TDD disproved). Use compound if A and B: or flatten to sequential ifs. ... is slot-filling only (for with param=...). Post-action set/run only works on @actions.*, NOT @utils.*. See references/syntax-reference.md for detailed examples.

💰 PRODUCTION GOTCHAS

See references/production-gotchas.md for the full production guide including: credit consumption table, lifecycle hooks (before_reasoning:/after_reasoning: syntax), supervision vs handoff, zero-hallucination routing with filter_from_agent/is_used_by_planner, action I/O metadata properties, action chaining, latch variable pattern, loop protection, token limits, progress indicators, VS Code limitations, and language block quirks.

Key highlights:

• Framework operations (@utils.*, if/else, set, lifecycle hooks) are FREE — only Flow/Apex/API actions cost 20 credits each
• before_reasoning:/after_reasoning: content goes directly under the block (NO instructions: wrapper)
• Use filter_from_agent: True + is_used_by_planner: True on outputs for zero-hallucination routing

Cross-Skill Orchestration

Tip: Open Agentforce Studio list view with sf org open authoring-bundle -o TARGET_ORG (v2.121.7+). Open a specific agent with sf org open agent --api-name MyAgent -o TARGET_ORG.

📋 QUICK REFERENCE: Agent Script Syntax

Block Structure (CORRECTED Order per Official Spec)

config:        # 1. Required: Agent metadata (developer_name, agent_type, default_agent_user)
variables:     # 2. Optional: State management (mutable/linked)
system:        # 3. Required: Global messages and instructions
connection:    # 4. Optional: Escalation routing — use `connection messaging:` (singular, NOT `connections:`)
knowledge:     # 5. Optional: Knowledge base config
language:      # 6. Optional: Locale settings
start_agent:   # 7. Required: Entry point (exactly one)
topic:         # 8. Required: Conversation topics (one or more)
# Note: Topics can override agent-level system: with a topic-level system: block

Config Block Field Names (CRITICAL)

# ✅ CORRECT config block:
config:
  developer_name: "my_agent"
  agent_description: "Handles customer support inquiries"
  agent_type: "AgentforceServiceAgent"
  default_agent_user: "agent_user@00dxx000001234.ext"

Naming Rules

• Only letters, numbers, underscores. Must begin with a letter.
• No spaces, no consecutive underscores, cannot end with underscore. Max 80 characters.

Instruction Syntax Patterns

Transition vs Delegation (CRITICAL DISTINCTION)

Expression Operators (Safe Subset)

Variable Types

⚠️ Linked variables CANNOT use object or list types. timestamp, currency, datetime, time, integer, long compile but are absent from official GA variable type docs — prefer date for date/time. These types are valid for action I/O only. See references/actions-reference.md for the full type matrix.

Connection Block (Escalation Routing)

⚠️ Service Agents Only. Use connection messaging: (singular, NOT connections:). The outbound_route_name requires flow:// prefix.

# Minimal form (no routing):
connection messaging:
   adaptive_response_allowed: True

# Full form with escalation routing:
connection messaging:
   outbound_route_type: "OmniChannelFlow"
   outbound_route_name: "flow://Route_from_Agent"
   escalation_message: "Connecting you with a specialist."
   adaptive_response_allowed: False

All-or-nothing rule: When outbound_route_type is present, ALL three route properties are required (outbound_route_type, outbound_route_name, escalation_message). Valid channel types: messaging, voice, web.

Two-Level Action System

Level 1: ACTION DEFINITION (in topic's `actions:` block)
   → Has `target:`, `inputs:`, `outputs:`, `description:`

Level 2: ACTION INVOCATION (in `reasoning.actions:` block)
   → References Level 1 via `@actions.name`
   → Specifies HOW to call it (with/set clauses)

For AiAuthoringBundle (Agent Script): flow:// and apex:// targets work directly — no GenAiFunction registration needed. I/O schemas (inputs: + outputs:) are REQUIRED for publish — omitting them causes “Internal Error.” See references/actions-reference.md for complete action types, target protocols, I/O name matching rules, and the Bare @InvocableMethod pattern.

🔄 WORKFLOW: Agent Development Lifecycle

Phase 1: Requirements & Design

1. Identify deterministic vs. subjective logic — Deterministic: security checks, thresholds, data lookups. Subjective: greetings, context understanding, NLG.
2. Design FSM architecture — Map topics as states, transitions as edges
3. Define variables — Mutable for state tracking, linked for session context

📋 Discovery Questions: Use the pre-authoring questionnaire in references/patterns-quick-ref.md to clarify Agent Identity, Topics, State, Actions, and Reasoning requirements before writing any code.

Phase 2: Agent Script Authoring

1. Create .agent file with required blocks (see Block Structure above)
2. Write topics with instruction resolution pattern: post-action checks at TOP, pre-LLM data loading, dynamic instructions for LLM
3. Configure actions with appropriate target protocols
4. Add available when guards to enforce security deterministically

Phase 3: Validation (LSP + CLI)

AUTOMATIC: LSP validation runs on every Write/Edit to .agent files — catches mixed tabs/spaces, lowercase booleans, missing blocks, invalid default_agent_user, and undefined topic references. Fix errors, re-save, repeat until clean.

# CLI Validation (before deploy):
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

Phase 4: Testing (Delegate to /sf-ai-agentforce-testing)

Batch testing (up to 100 cases), quality metrics (Completeness, Coherence, Topic/Action Assertions), LLM-as-Judge scoring.

Phase 5: Deployment & Activation

⚠️ CRITICAL: Use sf agent publish authoring-bundle, NOT sf project deploy start

1. Create bundle directory: force-app/main/default/aiAuthoringBundles/AgentName/
2. Add files: AgentName.agent + AgentName.bundle-meta.xml (NOT .aiAuthoringBundle-meta.xml)
3. Publish: sf agent publish authoring-bundle --api-name AgentName -o TARGET_ORG --json
4. Activate: sf agent activate --api-name AgentName -o TARGET_ORG (no --json support)

⚠️ Publishing does NOT activate. After sf agent publish, the new BotVersion is Inactive. Tests and preview run against the previous active version. You MUST run sf agent activate separately.

Full lifecycle: Validate → Deploy → Publish → Activate → (Deactivate → Re-publish → Re-activate)

Preview modes: Before activating, test with sf agent preview. Default mode simulates actions; add --use-live-actions to test with real org data. Use --apex-debug for Apex logging and --output-dir to save transcripts. See references/cli-guide.md for details.

Phase 5.5: CustomerWebClient Surface Enablement

⚠️ Without CustomerWebClient surface, Agent Builder Preview shows “Something went wrong” and Agent Runtime API returns 500. See references/customer-web-client.md for the required 6-step post-publish patch workflow.

Phase 6: CLI Operations

See references/cli-guide.md for retrieve, validate, publish, and generate commands. Always use --json to suppress spinner output.

Bundle Structure

force-app/main/default/aiAuthoringBundles/MyAgent/
├── MyAgent.agent            # Agent Script file
└── MyAgent.bundle-meta.xml  # NOT .aiAuthoringBundle-meta.xml!

The bundle-meta.xml contains only: <AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata"><bundleType>AGENT</bundleType></AiAuthoringBundle>

📊 SCORING SYSTEM (100 Points)

See references/scoring-rubric.md for the full 6-category breakdown, rubric details, and score report format.

Quick summary: Structure & Syntax (20), Deterministic Logic (25), Instruction Resolution (20), FSM Architecture (15), Action Configuration (10), Deployment Readiness (10). Score 90+ = deploy with confidence. Score <60 = BLOCK.

🔧 THE 6 DETERMINISTIC BUILDING BLOCKS

These execute as code, not suggestions. The LLM cannot override them.

📐 ARCHITECTURE PATTERNS

See references/architecture-patterns.md for Hub-and-Spoke, Verification Gate, and Post-Action Loop patterns with diagrams and code examples.

Post-Action Loop (most important): Topic re-resolves after action completes — put checks at TOP of instructions: ->.

🐛 DEBUGGING & COMMON ISSUES

See references/debugging-guide.md for the 6 span types (topic_enter, before_reasoning, reasoning, action_call, transition, after_reasoning), trace analysis workflow, and forensic debugging patterns.

Common Issues Quick Reference

Full issue catalog: See references/known-issues.md for 17+ platform bugs and workarounds.

Verification Protocol

When something fails, fetch the relevant canonical URL from references/official-sources.md and verify. See the diagnostic decision tree mapping 6 error categories to specific doc pages.

Self-Improvement

This skill’s resource files are editable. When you discover errors, new patterns, or platform bugs during a session — fix them in place. See references/known-issues.md for the issue template.

Deployment Gotchas (Validated by Testing)

Einstein Agent User Format (Org-Specific)

Formats vary: username@orgid.ext (production) or username.suffix@orgfarm.salesforce.com (dev). MANDATORY: Ask user to confirm which Einstein Agent User when creating a new agent.

sf data query -q "SELECT Username FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" -o YOUR_TARGET_ORG --json

📚 DOCUMENT MAP (Progressive Disclosure)

Tier 1: Reference Guides (Extracted from this skill)

Tier 2: Resource Guides (Comprehensive)

Tier 3: Quick References (Docs)

Tier 4: Templates

🔗 CROSS-SKILL INTEGRATION

MANDATORY Delegations

Integration Patterns

✅ DEPLOYMENT CHECKLIST

Deployment Checklist: Validate → Deploy → Publish → Activate. Each step has specific CLI commands and required flags. See references/cli-guide.md for the full deployment workflow with examples.

🚀 MINIMAL WORKING EXAMPLE

Minimal Working Example: See references/minimal-examples.md for a complete hello-world agent script with explanatory comments.

📖 OFFICIAL RESOURCES

• Agent Script Documentation — Primary reference
• Agent Script Recipes — Official examples
• Atlas Reasoning Engine — Reasoning internals

Full Registry: See references/official-sources.md for 14 primary doc URLs, 8 recipe URLs, diagnostic decision tree, and fallback search patterns.

📚 SOURCES & VERSION HISTORY

See references/sources.md for full source attributions (trailheadapps/agent-script-recipes, @kunello PR #20, aquivalabs/my-org-butler, and more).

See references/version-history.md for the complete changelog from v1.0.0 through v2.3.0.