sf-ai-agentforce

name	sf-ai-agentforce
description	Standard Agentforce platform skill. Covers Setup UI-based agent building, topic/action configuration, PromptTemplate metadata, Einstein Models API, GenAiFunction/GenAiPlugin setup, and custom Lightning types. For Agent Script DSL development, use sf-ai-agentscript instead.
license	MIT
compatibility	Requires API v65.0+ (Winter '26)
metadata	{"version":"2.1.0","author":"Jag Valaiyapathy"}

sf-ai-agentforce: Standard Agentforce Platform Development

Expert Agentforce developer specializing in the Setup UI / Agentforce Builder approach to agent development. Covers topic and action configuration, GenAiFunction/GenAiPlugin metadata, PromptTemplate authoring, Einstein Models API, and custom Lightning types.

Code-first alternative: For programmatic agent development using Agent Script DSL (.agent files), use sf-ai-agentscript instead. This skill covers the declarative, UI-driven approach.

---

Overview

Salesforce Agentforce enables organizations to build autonomous AI agents that handle customer interactions, automate tasks, and surface insights. This skill focuses on the standard platform approach:

• Agentforce Builder (Setup UI) for visual agent configuration
• GenAiFunction and GenAiPlugin metadata for registering actions
• PromptTemplate metadata for reusable AI prompts
• Einstein Models API (aiplatform.ModelsAPI) for native LLM access in Apex
• Custom Lightning Types (LightningTypeBundle) for rich agent action UIs

Two Approaches to Agentforce

Approach	Skill	When to Use
Setup UI / Agentforce Builder	sf-ai-agentforce (this skill)	Declarative agent config, point-and-click topics/actions
Agent Script DSL	sf-ai-agentscript	Code-first .agent files, FSM architecture, version-controlled agents

Both approaches produce agents that run on the same Agentforce runtime. Choose based on team preference and complexity requirements.

---

Core Concepts

Topics

Topics are the primary organizational unit for an agent's capabilities. Each topic groups related actions and instructions around a specific domain.

• Description: Tells the LLM planner when to route to this topic (must be specific and unambiguous)
• Scope: Defines what the topic can and cannot do (helps the planner make routing decisions)
• Instructions: Step-by-step guidance the agent follows when a topic is active
• Actions: The operations (Flow, Apex, Prompt Template) the agent can invoke within this topic

In the Agentforce Builder, topics are configured via Setup → Agentforce → Agents → [Agent] → Topics.

Actions

Actions are the executable operations an agent can perform. Each action wraps an underlying invocation target:

Target Type	Description	Registered Via
Flow	Invokes an Autolaunched Flow	GenAiFunction with invocationTargetType: flow
Apex	Invokes an @InvocableMethod	GenAiFunction with invocationTargetType: apex
Prompt Template	Invokes a PromptTemplate	GenAiFunction with invocationTargetType: prompt
Standard Action	Built-in platform actions (send email, create record)	Pre-registered by Salesforce

Instructions

Instructions guide the agent's behavior within a topic. They are natural language directives that tell the LLM:

• What steps to follow
• When to invoke specific actions
• How to handle edge cases and errors
• When to escalate to a human agent

---

Agent Builder Workflow

Step-by-Step: Creating an Agent via Setup UI

1. Navigate to Agentforce Builder

Setup → Agentforce → Agents → New Agent

2. Choose Agent Type

• Service Agent — Customer-facing support and service
• Employee Agent — Internal productivity and automation

3. Add Topics For each capability area:

• Provide a clear Name and Description
• Write Instructions that guide the agent's reasoning
• Add a Scope statement (what's in/out of bounds)

4. Configure Actions per Topic Assign actions to each topic. Actions can target:

• Autolaunched Flows (most common)
• Apex InvocableMethods (via GenAiFunction)
• Prompt Templates (for LLM-generated content)
• Standard platform actions

5. Set Action Inputs & Outputs For each action:

• Define inputs the agent collects from the user (slot filling)
• Define outputs the agent uses in its response
• Mark which outputs are displayable to the user

6. Configure Agent-Level Settings

• System Instructions: Global persona and behavior guidelines
• Default Agent User: The running user context for the agent
• Welcome Message: Initial greeting
• Error Message: Fallback when something goes wrong

7. Preview & Test

# Preview in Agentforce Builder (uses standard org auth)
sf agent preview --api-name MyAgent --target-org MyOrg

8. Publish

sf agent publish authoring-bundle --api-name MyAgent --target-org MyOrg

# Publish (skip metadata retrieve for CI/CD pipelines, v2.122.6+)
sf agent publish authoring-bundle --api-name MyAgent --skip-retrieve --target-org MyOrg

CLI Agent Lifecycle

Manage agent state via CLI (requires agent to be published first):

Command	Purpose
sf agent activate --api-name X --target-org Y	Activate a published agent (no --json support)
sf agent deactivate --api-name X --target-org Y	Deactivate an active agent (no --json support)

Note: sf agent create --spec <file> exists but is NOT recommended — agents created this way don't use Agent Script and are less flexible. Use the authoring-bundle workflow instead.

Full lifecycle: Validate → Deploy → Publish → Activate → (Deactivate → Re-publish → Re-activate)

Cross-references: sf-deploy for deployment orchestration, sf-ai-agentscript for Agent Script development.

Agent Spec Generation

Generate an agent spec YAML with sf agent generate agent-spec. Key flags:

• --type customer|internal — Agent type
• --role, --company-name, --company-description — Core identity
• --tone formal|casual|neutral — Conversational style
• --full-interview — Interactive prompt for all properties
• --spec <existing.yaml> — Iterative refinement of an existing spec

Full flag reference: See references/cli-commands.md for the complete generate agent-spec workflow with all 15+ flags.

---

GenAiFunction & GenAiPlugin Metadata

GenAiFunction

A GenAiFunction registers a single action that an Agentforce agent can invoke. It wraps an underlying Flow, Apex method, or Prompt Template.

Metadata XML Structure:

<?xml version="1.0" encoding="UTF-8"?>
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Look Up Order Status</masterLabel>
    <developerName>Lookup_Order_Status</developerName>
    <description>Retrieves the current status of a customer order</description>

    <!-- Target: the Flow, Apex, or Prompt to invoke -->
    <invocationTarget>Get_Order_Status_Flow</invocationTarget>
    <invocationTargetType>flow</invocationTargetType>

    <!-- Capability: tells the LLM planner WHEN to use this action -->
    <capability>
        Look up the current status of a customer's order when they
        ask about shipping, delivery, or order tracking.
    </capability>

    <!-- Inputs: what the agent collects from the user -->
    <genAiFunctionInputs>
        <developerName>orderNumber</developerName>
        <description>The customer's order number</description>
        <dataType>Text</dataType>
        <isRequired>true</>
    

    
    
        orderStatus
        Current status of the order
        Text
        true
    

File Location:

force-app/main/default/genAiFunctions/Lookup_Order_Status.genAiFunction-meta.xml

Invocation Target Types

invocationTargetType	Target Value	Notes
flow	Flow API name	Flow must be Active
apex	Apex class name	Class must have @InvocableMethod
prompt	PromptTemplate API name	Template must be Active

GenAiPlugin

A GenAiPlugin groups multiple GenAiFunction entries into a logical unit. This is useful for organizing related actions.

<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlugin xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Order Management Plugin</masterLabel>
    <developerName>Order_Management_Plugin</developerName>
    <description>Actions for managing customer orders</description>

    <genAiFunctions>
        <functionName>Lookup_Order_Status</functionName>
    </genAiFunctions>
    <genAiFunctions>
        <functionName>Cancel_Order</functionName>
    </genAiFunctions>
    <genAiFunctions>
        <functionName>Return_Order</functionName>
    </genAiFunctions>
</GenAiPlugin>

File Location:

force-app/main/default/genAiPlugins/Order_Management_Plugin.genAiPlugin-meta.xml

Deployment Order

1. Deploy the underlying Flow / Apex / PromptTemplate first
2. Deploy GenAiFunction metadata (references the targets)
3. Deploy GenAiPlugin metadata (references the functions)
4. Publish the Agent (references the plugin/functions via topics)

# Step 1: Deploy targets
sf project deploy start -m "Flow:Get_Order_Status_Flow" --target-org MyOrg

# Step 2: Deploy GenAiFunction
sf project deploy start -m "GenAiFunction:Lookup_Order_Status" --target-org MyOrg

# Step 3: Deploy GenAiPlugin (optional grouping)
sf project deploy start -m "GenAiPlugin:Order_Management_Plugin" --target-org MyOrg

# Step 4: Publish agent
sf agent publish authoring-bundle --api-name MyAgent --target-org MyOrg

---

PromptTemplate Configuration

PromptTemplate is the metadata type for creating reusable AI prompts. Templates can be invoked by Agentforce agents (via GenAiFunction), Einstein Prompt Builder, Apex code, and Flows.

Template Types: flexPrompt | salesGeneration | fieldCompletion | recordSummary

Variable Types: freeText (runtime input) | recordField (SObject field binding) | relatedList (child records) | resource (Static Resource)

Key Integration Points:

• Agent Action: Register a GenAiFunction with invocationTargetType: prompt
• Apex: ConnectApi.EinsteinLlm.generateMessagesForPromptTemplate()
• Flow: Use the "Prompt Template" action element

Full reference: See references/prompt-templates.md for complete metadata structure, variable types, examples, Data Cloud grounding, and best practices.

---

Models API

The Einstein Models API (aiplatform.ModelsAPI) enables native LLM access from Apex without external HTTP callouts. Use it for custom AI logic beyond what Agentforce topics/actions provide.

Available Models:

• sfdc_ai__DefaultOpenAIGPT4OmniMini — Cost-effective general tasks
• sfdc_ai__DefaultOpenAIGPT4Omni — Complex reasoning
• sfdc_ai__DefaultAnthropic — Nuanced understanding
• sfdc_ai__DefaultGoogleGemini — Multimodal tasks

Key Patterns:

• Queueable for single-record async AI processing
• Batch for bulk processing (scope size 10–20)
• Platform Events for notifying completion to LWC/Flow

Prerequisites: Einstein Generative AI enabled, API v61.0+, Einstein Generative AI User permission set assigned.

Full reference: See references/models-api.md for complete Apex examples, Queueable/Batch patterns, Chatter integration, and governor limit guidance.

---

Custom Lightning Types

Custom Lightning Types (LightningTypeBundle) define structured data types with custom UI components for agent action inputs and outputs. When an agent action needs a rich input form or a formatted output display, create a custom type with:

• schema.json — JSON Schema data structure definition
• editor.json — Custom input collection UI (lightning components)
• renderer.json — Custom output display UI (lightning components)

Requirements: API v64.0+ (Fall '25), Enhanced Chat V2 enabled in Service Cloud.

File Structure:

force-app/main/default/lightningTypeBundles/OrderDetails/
├── schema.json
├── editor.json
├── renderer.json
└── OrderDetails.lightningTypeBundle-meta.xml

Full reference: See references/custom-lightning-types.md for complete schema examples, editor/renderer configuration, and integration with GenAiFunction.

---

Orchestration Order

Prerequisite skills must run in this order:

sf-metadata → sf-apex → sf-flow → sf-ai-agentforce → sf-deploy

Why this order:

1. sf-metadata — Custom objects/fields must exist before Apex/Flows reference them
2. sf-apex — InvocableMethod classes must be deployed before Flows or GenAiFunctions reference them
3. sf-flow — Flows must be active before GenAiFunctions can target them
4. sf-ai-agentforce (this skill) — GenAiFunction/GenAiPlugin metadata and agent configuration
5. sf-deploy — Final deployment and agent publishing

MANDATORY Delegations:

Requirement	Delegate To	Why
Flow creation	Use the sf-flow skill	110-point validation, proper XML
Apex creation	Use the sf-apex skill	InvocableMethod generation, 150-point scoring
Deployment	Use the sf-deploy skill	Centralized deployment orchestration

---

Cross-Skill Integration

Skill	Purpose	When to Use
sf-ai-agentscript	Agent Script DSL (code-first)	Writing .agent files with FSM architecture
sf-ai-agentforce-testing	Agent testing	Test execution, coverage analysis, agentic fix loops
sf-flow	Flow actions	Creating Autolaunched Flows for agent actions
sf-apex	Apex actions	Writing InvocableMethod classes for agent actions
sf-deploy	Deployment	Publishing agents, deploying metadata
sf-metadata	Object/field setup	Creating SObjects and fields that actions reference
sf-integration	External APIs	Named Credentials, External Services for agent callouts

Integration Patterns

Direction	Pattern	Notes
Agent → Flow	GenAiFunction targets Flow	Most common action pattern
Agent → Apex	GenAiFunction targets InvocableMethod	For complex business logic
Agent → Prompt	GenAiFunction targets PromptTemplate	For AI-generated content
Agent → Custom Type	GenAiFunction uses LightningTypeBundle	Rich input/output UIs
Agent → External API	Flow/Apex wraps Named Credential callout	Via sf-integration skill

---

Key Insights

Insight	Issue	Fix
GenAiFunction requires active target	Deploying GenAiFunction before its Flow/Apex target	Deploy targets first, then GenAiFunction
PromptTemplate field bindings	{!variableName} must match variable developerName exactly	Check spelling and case sensitivity
Custom Lightning Types require v64.0+	Bundle won't deploy on older API versions	Set <version>64.0</version> or higher in package.xml
GenAiPlugin groups functions	Individual GenAiFunctions must exist before the plugin	Deploy GenAiFunctions before GenAiPlugin
Capability text is critical	Vague capability descriptions cause poor routing	Write specific, scenario-based capability text
Enhanced Chat V2 for custom types	Custom type UI won't render without it	Enable Enhanced Chat V2 in Setup → Chat Settings
Models API needs async context	Synchronous calls in triggers will timeout	Use Queueable with Database.AllowsCallouts
Input/output names must match	GenAiFunction input names must match Flow variable API names	Verify exact name match (case-sensitive)
Validation before publish	Skipping validation causes late-stage failures	Always run sf agent validate authoring-bundle first
Data type mapping	GenAiFunction dataType must align with target parameter types	Use Text, Number, Boolean, Date as appropriate

---

Scoring System (100 Points)

Categories

Category	Points	Key Criteria
Agent Configuration	20	System instructions, welcome/error messages, agent user set
Topic & Action Design	25	Clear descriptions, proper scope, logical routing, capability text
Metadata Quality	20	Valid GenAiFunction/GenAiPlugin XML, correct target types, input/output definitions
Integration Patterns	15	Proper orchestration order, dependency management, cross-skill delegation
PromptTemplate Usage	10	Variable bindings correct, template types appropriate, prompts well-structured
Deployment Readiness	10	Validation passes, dependencies deployed first, package.xml correct

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

Validation Report Format

Score: 87/100 ⭐⭐⭐⭐ Very Good
├─ Agent Configuration:     18/20 (90%)
├─ Topic & Action Design:   22/25 (88%)
├─ Metadata Quality:        17/20 (85%)
├─ Integration Patterns:    13/15 (87%)
├─ PromptTemplate Usage:     9/10 (90%)
└─ Deployment Readiness:     8/10 (80%)

Issues:
⚠️ [Metadata] GenAiFunction "Cancel_Order" missing output definition
⚠️ [Integration] Flow "Get_Order_Status" not yet deployed to org
✓ All PromptTemplate variable bindings valid
✓ GenAiPlugin references resolve correctly

---

Document Map

Tier 2: Detailed References

Document	Description	Read When
references/cli-commands.md	CLI command reference for agent lifecycle, generation, and publishing	Using sf agent commands
references/prompt-templates.md	Complete PromptTemplate metadata, variable types, Data Cloud grounding	Authoring reusable AI prompts
references/models-api.md	aiplatform.ModelsAPI Apex patterns, Queueable/Batch integration	Building custom AI logic in Apex
references/custom-lightning-types.md	LightningTypeBundle schema/editor/renderer configuration	Creating rich action input/output UIs

Cross-Skill References

Need	Skill
Agent Script DSL development	sf-ai-agentscript
Agent testing & coverage	sf-ai-agentforce-testing
Flow creation for actions	sf-flow
Apex InvocableMethod classes	sf-apex
Metadata deployment	sf-deploy

---

Version History

Version	Date	Changes
2.0.0	2026-02-07	Complete rewrite. Skill refocused on standard Agentforce platform (Setup UI, GenAiFunction/GenAiPlugin, PromptTemplate, Models API, Custom Lightning Types). Agent Script DSL content moved to sf-ai-agentscript.

---

Sources & Acknowledgments

Source	Contribution
Salesforce Agentforce Documentation	Official platform reference
Salesforce Diaries	Models API patterns, Custom Lightning Types guide
trailheadapps/agent-script-recipes	Official Salesforce examples
Jag Valaiyapathy	Skill authoring, scoring system, orchestration design

---

License

MIT License. See LICENSE file in sf-ai-agentforce folder. Copyright (c) 2024–2026 Jag Valaiyapathy