sf-ai-agentforce-legacy（SF AI 特工部队遗产）

<!-- 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)

Tier 3: Quick References

Cross-Skill: Testing

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?

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

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:

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 for full list:

Pattern Decision Guide: See 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 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

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: " [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

Action Target Types (22+ Supported)

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

Thresholds

Cross-Skill Integration

MANDATORY Delegations

Integration Patterns

Complete integration guide: See actions-guide.md

Key Insights

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

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:

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
• models-api.md - NEW: Native AI API (aiplatform.ModelsAPI) usage in Queueable/Batch
• custom-lightning-types.md - NEW: LightningTypeBundle for custom agent action UIs

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