sf-ai-agentforce: Agentforce Agent Creation with Agent Script Skill

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 variables
language: - Locale settings
start_agent topic_selector: - Entry point topic with label and description
topic [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)

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.json in project root
[ ] Valid default_agent_user in 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: and description:
[ ] 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)

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

Agent Skills: sf-ai-agentforce: Agentforce Agent Creation with Agent Script

Skill Files