majiayu000 sf-ai-agentforce: Agentforce Agent Creation with Agent Script
Expert Agentforce developer specializing in Agent Script syntax, topic design, and action integration. Generate production-ready agents that leverage LLM reasoning with deterministic business logic.
Core Responsibilities
- Agent Creation: Generate complete Agentforce agents using Agent Script
- Topic Management: Create and configure agent topics with proper transitions
- Action Integration: Connect actions to Flows (directly) or Apex (via Agent Actions)
- Validation & Scoring: Score agents against best practices (0-100 points)
- Deployment: Publish agents using
sf agent publish authoring-bundle
Document Map (Progressive Disclosure)
Read documents in tier order based on what you need:
Tier 2: Resource Guides (NEW)
| Need | Document | Description |
|---|---|---|
| Complete syntax reference | agent-script-reference.md | Full Agent Script DSL, patterns, reserved words, new features |
| Topic design & routing | topics-guide.md | Topic structure, transitions, delegation, multi-topic agents |
| Action implementation | actions-guide.md | Flow/Apex actions, data types, advanced fields, slot filling |
| Testing approaches | testing-guide.md | Preview modes, Agent Testing Center, agentic fix loops |
| Deployment & CLI | deployment-guide.md | Two deployment methods, CLI commands, troubleshooting |
Tier 3: Quick References
| Need | Document | Description |
|---|---|---|
| CLI commands | cli-guide.md | sf agent commands, preview, publish |
| Patterns & practices | patterns-and-practices.md | Decision tree + best practices |
Cross-Skill: Testing
| Need | Skill | Description |
|---|---|---|
| Agent Testing | sf-ai-agentforce-testing |
Test execution, coverage analysis, agentic fix loops |
Quick Links:
- Key Insights Table - Common errors and fixes
- Scoring System - 6-category validation
- Required Files Checklist - Pre-deployment verification
Official Reference:
- trailheadapps/agent-script-recipes - Salesforce's official Agent Script examples
Critical Warnings
API Version Requirement
Agent Script requires API v65.0+ (Winter '26 or later)
Before creating agents, verify:
sf org display --target-org [alias] --json | jq '.result.apiVersion'
If API version < 65, Agent Script features won't be available.
Orchestration Order
sf-metadata → sf-apex → sf-flow → sf-deploy → sf-ai-agentforce (you are here: sf-ai-agentforce)
Why this order?
- sf-metadata: Custom objects/fields must exist before Apex or Flows reference them
- sf-apex: InvocableMethod classes must be deployed before Flow wrappers call them
- sf-flow: Flows must be created AND deployed before agents can reference them
- sf-deploy: Deploy all metadata before publishing agent
- sf-ai-agentforce: Agent is published LAST after all dependencies are in place
MANDATORY Delegation:
- Flows: ALWAYS use
Skill(skill="sf-flow")- never manually write Flow XML - Deployments: Use
Skill(skill="sf-deploy")for all deployments - Apex: ALWAYS use
Skill(skill="sf-apex")for InvocableMethod classes
See docs/orchestration.md for complete workflow.
File Structure
| Method | Path | Files | Deploy Command |
|---|---|---|---|
| AiAuthoringBundle | aiAuthoringBundles/[Name]/ |
[Name].agent + .bundle-meta.xml |
sf agent publish authoring-bundle --api-name [Name] |
| GenAiPlannerBundle | genAiPlannerBundles/[Name]/ |
[Name].genAiPlannerBundle + agentScript/[Name]_definition.agent |
sf project deploy start --source-dir [path] |
XML templates: See templates/ for bundle-meta.xml and genAiPlannerBundle examples.
GenAiPlannerBundle agents do NOT appear in Agentforce Studio UI.
Full deployment method comparison: See deployment-guide.md
Workflow (5-Phase Pattern)
Phase 1: Requirements Gathering
Use AskUserQuestion to gather:
- Agent purpose: What job should this agent do?
- Topics needed: What categories of actions? (e.g., FAQ, Order Management, Support)
- Actions required: Flow-based? Apex-based? External API?
- Variables: What state needs to be tracked?
- System persona: What tone/behavior should the agent have?
Then:
- Check existing agents:
Glob: **/aiAuthoringBundles/**/*.agent - Check for sfdx-project.json to confirm Salesforce project structure
- Create TodoWrite tasks
Phase 2: Template Selection / Design
Select appropriate pattern based on requirements - see agent-script-reference.md for full list:
| Pattern | Use When | Template |
|---|---|---|
| Hello World | Learning / Minimal agent | templates/agents/hello-world.agent |
| Simple Q&A | Single topic, no actions | templates/agents/simple-qa.agent |
| Multi-Topic | Multiple conversation modes | templates/agents/multi-topic.agent |
| Action-Based | External integrations needed | templates/components/flow-action.agent |
Pattern Decision Guide: See patterns-and-practices.md for detailed decision tree.
Template Path Resolution (try in order):
- Marketplace folder:
~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/templates/[path] - Project folder:
[project-root]/sf-ai-agentforce/templates/[path]
Phase 3: Generation / Validation
Create TWO files at:
force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].agent
force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].bundle-meta.xml
Required bundle-meta.xml content:
<?xml version="1.0" encoding="UTF-8"?>
<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<bundleType>AGENT</bundleType>
</AiAuthoringBundle>
Required .agent blocks:
system:- Instructions and messages (MUST BE FIRST)config:- Agent metadata (agent_name, agent_label, description, default_agent_user)variables:- Linked and mutable variableslanguage:- Locale settingsstart_agent topic_selector:- Entry point topic with label and descriptiontopic [name]:- Additional topics (each with label and description)
Complete syntax reference: See agent-script-reference.md
Validation Report Format (6-Category Scoring 0-100):
Score: 85/100 ⭐⭐⭐⭐ Very Good
├─ Structure & Syntax: 18/20 (90%)
├─ Topic Design: 16/20 (80%)
├─ Action Integration: 18/20 (90%)
├─ Variable Management: 13/15 (87%)
├─ Instructions Quality: 12/15 (80%)
└─ Security & Guardrails: 8/10 (80%)
Issues:
⚠️ [Syntax] Line 15: Inconsistent indentation (mixing tabs and spaces)
⚠️ [Topic] Missing label for topic 'checkout'
✓ All topic references valid
✓ All variable references valid
Phase 4: Deployment
Complete deployment workflow: See deployment-guide.md
Quick workflow:
# 1. Deploy dependencies first (flows, apex)
sf project deploy start --metadata Flow --target-org [alias]
# 2. ⚠️ VALIDATE AGENT (MANDATORY)
sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]
# 3. Deploy agent (Option A: Metadata API - recommended)
sf project deploy start --source-dir force-app/main/default/aiAuthoringBundles/[AgentName] --target-org [alias]
# 4. Activate agent
sf agent activate --api-name [AgentName] --target-org [alias]
NEW vs UPDATING agents: See deployment-guide.md for method selection.
Phase 5: Verification
✓ Agent Complete: [AgentName]
Type: Agentforce Agent | API: 65.0+
Location: force-app/main/default/aiAuthoringBundles/[AgentName]/
Files: [AgentName].agent, [AgentName].bundle-meta.xml
Validation: PASSED (Score: XX/100)
Topics: [N] | Actions: [M] | Variables: [P]
Published: Yes | Activated: [Yes/No]
Next Steps:
1. Open in Studio: sf org open agent --api-name [AgentName]
2. Test in Agentforce Testing Center
3. Activate when ready: sf agent activate
Phase 6: Testing (via sf-ai-agentforce-testing)
Complete testing guide: See testing-guide.md
After deploying your agent, use the sf-ai-agentforce-testing skill:
# Invoke the testing skill
Skill(skill="sf-ai-agentforce-testing", args="Test agent [AgentName] and fix any failures")
The testing skill provides:
- Test spec generation from agent metadata
- 100-point test scoring across 5 categories
- Agentic fix loops - auto-fix failing tests (max 3 iterations)
- Coverage analysis for topics, actions, guardrails, escalation
Quick Reference
Minimal Working Example
system:
instructions: "You are a helpful assistant. Be professional and friendly."
messages:
welcome: "Hello! How can I help you today?"
error: "I apologize, but I encountered an issue."
config:
agent_name: "My_Agent"
default_agent_user: "user@example.com"
agent_label: "My Agent"
description: "A helpful assistant agent"
variables:
EndUserId: linked string
source: @MessagingSession.MessagingEndUserId
description: "Messaging End User ID"
RoutableId: linked string
source: @MessagingSession.Id
description: "Messaging Session ID"
ContactId: linked string
source: @MessagingEndUser.ContactId
description: "Contact ID"
language:
default_locale: "en_US"
additional_locales: ""
all_additional_locales: False
start_agent topic_selector:
label: "Topic Selector"
description: "Routes users to appropriate topics"
reasoning:
instructions: ->
| Determine what the user needs.
actions:
go_help: @utils.transition to @topic.help
topic help:
label: "Help"
description: "Provides help to users"
reasoning:
instructions: ->
| Answer the user's question helpfully.
Complete syntax and patterns: See agent-script-reference.md
Action Target Types (22+ Supported)
| Type | Target Syntax | Recommended |
|---|---|---|
| Flow (native) | flow://FlowAPIName |
Best choice |
| Apex (via Flow) | flow://ApexWrapperFlow |
Recommended |
| Prompt Template | generatePromptResponse://TemplateName |
For LLM tasks |
| Standard Action | standardInvocableAction://sendEmail |
Built-in actions |
Complete action reference: See actions-guide.md
Topic Design
Hub-and-Spoke Pattern (Recommended):
start_agent= Hub (routes to topics)- Topics = Spokes (feature areas)
- Each topic can transition back to hub
Complete topic patterns: See topics-guide.md
Scoring System (100 Points)
Categories
| Category | Points | Key Criteria |
|---|---|---|
| Structure & Syntax | 20 | Valid syntax, consistent indentation, required blocks |
| Topic Design | 20 | Labels/descriptions, logical transitions, naming |
| Action Integration | 20 | Valid targets, input descriptions, no reserved words |
| Variable Management | 15 | Descriptions, required linked vars, appropriate types |
| Instructions Quality | 15 | Clear reasoning, edge cases, valid templates |
| Security & Guardrails | 10 | System guardrails, validation, error handling |
Thresholds
| Score | Rating | Action |
|---|---|---|
| 90-100 | ⭐⭐⭐⭐⭐ Excellent | Deploy with confidence |
| 80-89 | ⭐⭐⭐⭐ Very Good | Minor improvements suggested |
| 70-79 | ⭐⭐⭐ Good | Review before deploy |
| 60-69 | ⭐⭐ Needs Work | Address issues before deploy |
| <60 | ⭐ Critical | Block deployment |
Cross-Skill Integration
MANDATORY Delegations
| Requirement | Skill/Agent | Why | Never Do |
|---|---|---|---|
| Flow Creation | Skill(skill="sf-flow") |
110-point validation, proper XML ordering, prevents errors | Manually write Flow XML |
| ALL Deployments | Skill(skill="sf-deploy") |
Centralized deployment | Direct CLI |
| Apex Creation | Skill(skill="sf-apex") |
@InvocableMethod generation | Manually write Apex |
Integration Patterns
| Direction | Pattern | Supported |
|---|---|---|
| sf-agentforce → sf-flow | Create Flow-based actions | Full |
| sf-agentforce → sf-apex | Create Apex via Flow wrapper | Via Flow |
| sf-agentforce → sf-deploy | Deploy agent metadata | Full |
| sf-agentforce → sf-metadata | Query object structure | Full |
| sf-agentforce → sf-integration | External API actions | Via Flow |
Complete integration guide: See actions-guide.md
Key Insights
| Insight | Issue | Fix |
|---|---|---|
| File Extension | .agentscript not recognized |
Use .agent |
| Config Field | developer_name OR agent_name |
Both work (aliases for same field) |
| Instructions Syntax | instructions:-> fails |
Use instructions: -> (space!) |
| Topic Fields | Missing label fails deploy |
Add both label and description |
| Linked Variables | Missing context variables | Add EndUserId, RoutableId, ContactId |
| Language Block | Missing causes deploy failure | Add language: block |
| Bundle XML | Missing causes deploy failure | Create .bundle-meta.xml file |
| Indentation Consistency | Mixing tabs/spaces causes parse errors | Use TABS consistently (recommended) |
@variables is plural |
@variable.x fails |
Use @variables.x |
| Boolean capitalization | true/false invalid |
Use True/False |
| ⚠️ Validation Required | Skipping validation causes late-stage failures | ALWAYS run sf agent validate authoring-bundle BEFORE deploy |
| Flow Variable Names | Mismatched names cause "Internal Error" | Agent Script input/output names MUST match Flow variable API names exactly |
| Action Location | Top-level actions fail | Define actions inside topics |
| start_agent Actions | Flow actions in start_agent fail in AiAuthoringBundle |
Use start_agent only for @utils.transition, put flow actions in topic blocks |
| System Instructions | Pipe | syntax fails in system: block |
Use single quoted string only |
| Escalate Description | Inline description fails | Put description: on separate indented line |
| Reserved Words | description as input fails |
Use alternative names (e.g., case_description) |
| ⚠️ Slot Filling Reliability | LLM sends empty JSON, wrong field names, or wrong values | Use deterministic collection: dedicated setter action + single-use (available when @var == "") + null guards. See actions-guide.md |
| Explicit Action References | LLM doesn't consistently call correct actions | Reference actions in instructions: {!@actions.capture_id}. Improves LLM reliability. |
Complete troubleshooting: See deployment-guide.md
Required Files Checklist
Before deployment, ensure you have:
-
force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].agent -
force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].bundle-meta.xml -
sfdx-project.jsonin project root - Valid
default_agent_userin config block - All linked variables (EndUserId, RoutableId, ContactId)
- Language block present
- ⚠️ Validation passed:
sf agent validate authoring-bundle --api-name [AgentName]returns 0 errors - All topics have
label:anddescription: - No reserved words used as input/output names
- Flow/Apex dependencies deployed to org first
LSP Integration (Real-Time Validation)
This skill includes Language Server Protocol (LSP) integration for real-time Agent Script validation.
Prerequisites
VS Code with Agent Script Extension (Required)
- Open VS Code → Extensions (Cmd+Shift+X)
- Search: "Agent Script" by Salesforce
- Install the extension
Node.js 18+ (Required)
- Check:
node --version - Install:
brew install node(macOS)
- Check:
Features
When you edit .agent files, the LSP automatically provides:
| Feature | Description |
|---|---|
| Syntax Validation | Real-time error detection |
| Auto-Fix Loop | Claude automatically fixes errors (max 3 attempts) |
| Fast Feedback | ~50ms response time |
Troubleshooting
"LSP server not found"
- Install VS Code Agent Script extension
- Verify:
ls ~/.vscode/extensions/salesforce.agent-script-*
"Node.js not found"
- Install Node.js 18+:
brew install node
Validation not triggering
- Ensure hooks are enabled in Claude Code settings
- Check:
ls ~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/hooks/
Validation
Manual validation (if hooks don't fire):
python3 ~/.claude/plugins/marketplaces/sf-skills/sf-agentforce/hooks/scripts/validate_agentforce.py <file_path>
Scoring: 100 points / 6 categories. Minimum 60 (60%) for deployment.
Hooks not firing? Check: CLAUDE_PLUGIN_ROOT set, hooks.json valid, Python 3 in PATH, file matches pattern *.agent.
Reference & Dependencies
Resource Guides (NEW):
- agent-script-reference.md - Complete Agent Script DSL
- topics-guide.md - Topic design and routing
- actions-guide.md - Action implementation patterns
- testing-guide.md - Testing approaches
- deployment-guide.md - Deployment and CLI
Quick References:
- agent-script-reference.md - Full syntax + gotchas
- cli-guide.md - sf agent commands, preview, publish
- actions-reference.md - Flow, Apex, Prompt actions
- patterns-and-practices.md - Decision tree + best practices
Dependencies: sf-deploy (optional) for additional deployment options. Install: /plugin install github:Jaganpro/sf-skills/sf-deploy
Notes: API 65.0+ required | Agent Script is GA (2025) | Block if score < 60
License
MIT License. See LICENSE file in sf-ai-agentforce folder. Copyright (c) 2024-2025 Jag Valaiyapathy