sf-ai-agentforce-legacy

1. Agent Creation: Generate complete Agentforce agents using Agent Script
2. Topic Management: Create and configure agent topics with proper transitions
3. Action Integration: Connect actions to Flows (directly) or Apex (via Agent Actions)
4. Validation & Scoring: Score agents against best practices (0-100 points)
5. Deployment: Publish agents using sf agent publish authoring-bundle

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](resources/agent-script-reference.md) | Full Agent Script DSL, patterns, reserved words, new features |

| Topic design & routing | [topics-guide.md](resources/topics-guide.md) | Topic structure, transitions, delegation, multi-topic agents |

| Action implementation | [actions-guide.md](resources/actions-guide.md) | Flow/Apex actions, data types, advanced fields, slot filling |

| Testing approaches | [testing-guide.md](resources/testing-guide.md) | Preview modes, Agent Testing Center, agentic fix loops |

| Deployment & CLI | [deployment-guide.md](resources/deployment-guide.md) | Two deployment methods, CLI commands, troubleshooting |

Tier 3: Quick References

| Need | Document | Description |

|------|----------|-------------|

| CLI commands | [cli-guide.md](docs/cli-guide.md) | sf agent commands, preview, publish |

| Patterns & practices | [patterns-and-practices.md](docs/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](#-key-insights) - Common errors and fixes
• [Scoring System](#scoring-system-100-points) - 6-category validation
• [Required Files Checklist](#required-files-checklist) - Pre-deployment verification

Official Reference:

• [trailheadapps/agent-script-recipes](https://github.com/trailheadapps/agent-script-recipes) - Salesforce's official Agent Script examples

---

API Version Requirement

Agent Script requires API v65.0+ (Winter '26 or later)

Before creating agents, verify:

```bash

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?

1. sf-metadata: Custom objects/fields must exist before Apex or Flows reference them
2. sf-apex: InvocableMethod classes must be deployed before Flow wrappers call them
3. sf-flow: Flows must be created AND deployed before agents can reference them
4. sf-deploy: Deploy all metadata before publishing agent
5. 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](resources/deployment-guide.md#deployment-methods)

---

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:

1. Check existing agents: Glob: /aiAuthoringBundles//*.agent
2. Check for sfdx-project.json to confirm Salesforce project structure
3. Create TodoWrite tasks

Phase 2: Template Selection / Design

Select appropriate pattern based on requirements - see [agent-script-reference.md](resources/agent-script-reference.md#common-patterns) 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](docs/patterns-and-practices.md) for detailed decision tree.

Template Path Resolution (try in order):

1. Marketplace folder: ~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/templates/[path]
2. 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

AGENT

```

Required .agent blocks:

1. system: - Instructions and messages (MUST BE FIRST)
2. config: - Agent metadata (agent_name, agent_label, description, default_agent_user)
3. variables: - Linked and mutable variables
4. language: - Locale settings
5. start_agent topic_selector: - Entry point topic with label and description
6. topic [name]: - Additional topics (each with label and description)

Complete syntax reference: See [agent-script-reference.md](resources/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](resources/deployment-guide.md#deployment-workflow)

Quick workflow:

```bash

# 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](resources/deployment-guide.md#new-agents-vs-updating-existing-agents) 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](resources/testing-guide.md)

After deploying your agent, use the sf-ai-agentforce-testing skill:

```bash

# 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

---

Minimal Working Example

```agentscript

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](resources/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](resources/actions-guide.md#complete-action-type-reference)

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](resources/topics-guide.md#routing-patterns)

---

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 |

---

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](resources/actions-guide.md#apex-actions-via-flow-wrapper)

---

| 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](resources/actions-guide.md#slot-filling-patterns) |

| 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](resources/deployment-guide.md#troubleshooting)

---

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

---

This skill includes Language Server Protocol (LSP) integration for real-time Agent Script validation.

Prerequisites

1. VS Code with Agent Script Extension (Required)

- Open VS Code → Extensions (Cmd+Shift+X)

- Search: "Agent Script" by Salesforce

- Install the extension

1. 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/

---

Manual validation (if hooks don't fire):

```bash

python3 ~/.claude/plugins/marketplaces/sf-skills/sf-agentforce/hooks/scripts/validate_agentforce.py

```

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.

---

Resource Guides (NEW):

• [agent-script-reference.md](resources/agent-script-reference.md) - Complete Agent Script DSL
• [topics-guide.md](resources/topics-guide.md) - Topic design and routing
• [actions-guide.md](resources/actions-guide.md) - Action implementation patterns
• [testing-guide.md](resources/testing-guide.md) - Testing approaches
• [deployment-guide.md](resources/deployment-guide.md) - Deployment and CLI
• [models-api.md](docs/models-api.md) - NEW: Native AI API (aiplatform.ModelsAPI) usage in Queueable/Batch
• [custom-lightning-types.md](docs/custom-lightning-types.md) - NEW: LightningTypeBundle for custom agent action UIs

Quick References:

• [agent-script-reference.md](docs/agent-script-reference.md) - Full syntax + gotchas
• [cli-guide.md](docs/cli-guide.md) - sf agent commands, preview, publish
• [actions-reference.md](docs/actions-reference.md) - Flow, Apex, Prompt actions
• [patterns-and-practices.md](docs/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

---

MIT License. See LICENSE file in sf-ai-agentforce folder.

Copyright (c) 2024-2025 Jag Valaiyapathy