home / skills / jaganpro / sf-skills / sf-ai-agentforce-legacy
/sf-ai-agentforce-legacy
This skill helps maintain legacy Agentforce agents by generating and validating Agent Script based configurations, topics, and actions with structured scoring.
npx playbooks add skill jaganpro/sf-skills --skill sf-ai-agentforce-legacyReview the files below or copy the command above to add this skill to your agents.
---
name: sf-ai-agentforce-legacy
description: >
[DEPRECATED] Creates Agentforce agents using Agent Script syntax with 100-point scoring.
For new agent development, use sf-ai-agentscript instead.
This skill remains available for maintaining existing agents built with legacy patterns.
license: MIT
compatibility: "Requires API v65.0+ (Winter '26) for deployment"
metadata:
version: "1.1.0"
author: "Jag Valaiyapathy"
scoring: "100 points across 6 categories"
hooks:
PreToolUse:
- matcher: Bash
hooks:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
timeout: 5000
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "python3 ${SKILL_HOOKS}/agentscript-lsp-validate.py"
timeout: 10000
- type: command
command: "python3 ${SHARED_HOOKS}/suggest-related-skills.py sf-ai-agentforce-legacy"
timeout: 5000
SubagentStop:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/chain-validator.py sf-ai-agentforce-legacy"
timeout: 5000
---
<!-- TIER: 1 | ENTRY POINT -->
<!-- This is the starting document - read this FIRST -->
<!-- Progressive disclosure: SKILL.md → Resources → Quick Refs → Detailed Refs → Specialized Guides -->
> ⚠️ **DEPRECATED**: This skill has been superseded by **sf-ai-agentscript**.
>
> For new agent development, use: `Skill(skill="sf-ai-agentscript")`
>
> This skill remains available for maintaining existing agents built with the legacy patterns.
# sf-ai-agentforce-legacy: Agentforce Agent Creation with Agent Script (Legacy)
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
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`
## 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](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
---
## Critical Warnings
### 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)
---
## 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**:
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
<?xml version="1.0" encoding="UTF-8"?>
<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<bundleType>AGENT</bundleType>
</AiAuthoringBundle>
```
**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
---
## Quick Reference
### 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: "[email protected]"
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)
---
## 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](resources/actions-guide.md#apex-actions-via-flow-wrapper)
---
## 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](resources/actions-guide.md#slot-filling-patterns)** |
| **Explicit Action References** | LLM doesn't consistently call correct actions | Reference actions in instructions: `{[email protected]_id}`. Improves LLM reliability. |
**Complete troubleshooting**: See [deployment-guide.md](resources/deployment-guide.md#troubleshooting)
---
## 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
1. **VS Code with Agent Script Extension** (Required)
- Open VS Code → Extensions (Cmd+Shift+X)
- Search: "Agent Script" by Salesforce
- Install the extension
2. **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):
```bash
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](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
---
## License
MIT License. See LICENSE file in sf-ai-agentforce folder.
Copyright (c) 2024-2025 Jag Valaiyapathy
This skill provides legacy support for creating Agentforce agents using Agent Script syntax and a 100-point validation scoring model. It is intended only for maintaining existing agents built with legacy patterns and is deprecated in favor of a newer Agent Script skill. Use it to generate, validate, and publish Agentforce authoring bundles that depend on the older conventions.
The skill generates complete .agent bundles and the required bundle-meta.xml, validates agent structure across six scoring categories (0–100), and guides deployment steps. It inspects agent blocks (system, config, variables, language, start_agent, topic) and checks topic design, action targets, variable linkage, instructions quality, and security guardrails. It also enforces orchestration order and delegation to Flow, Apex, and deploy skills.
Is this skill recommended for new agent development?
No. This skill is deprecated. Use the newer sf-ai-agentscript skill for all new agent development.
What API version is required to use Agent Script features?
Agent Script requires Salesforce API version 65.0 or later; confirm with sf org display before creating agents.