Agentforce Agent Deployment Guide

Agentforce Agent Deployment Guide

Complete DevOps guide for deploying Agentforce agents using SF CLI

Overview

This guide covers the complete deployment lifecycle for Agentforce agents, including:

• Agent metadata types and pseudo metadata
• Sync operations (retrieve/deploy)
• Lifecycle management (activate/deactivate)
• Full deployment workflows

Related Skills:

• sf-ai-agentscript - Agent Script authoring and publishing (recommended for new agents)
• sf-ai-agentforce - Agentforce platform setup (Agent Builder, PromptTemplate, Models API)
• sf-deploy - This skill - deployment orchestration

Agent Metadata Types

Agentforce agents consist of multiple metadata components:

Metadata Hierarchy

Bot (Agent Definition)
└── BotVersion (Version Config)
    └── GenAiPlannerBundle (Reasoning Engine)
        ├── GenAiPlugin (Topic 1)
        │   ├── GenAiFunction (Action 1)
        │   └── GenAiFunction (Action 2)
        └── GenAiPlugin (Topic 2)
            └── GenAiFunction (Action 3)

Agent Pseudo Metadata Type

The Agent pseudo metadata type is a convenience wrapper that retrieves or deploys all agent-related components at once.

Using the Agent Pseudo Type

# Retrieve agent + all dependencies from org
sf project retrieve start --metadata Agent:[AgentName] --target-org [alias]

# Deploy agent metadata to org
sf project deploy start --metadata Agent:[AgentName] --target-org [alias]

What Gets Synced

When using --metadata Agent:[Name]:

Retrieved/Deployed:

• Bot - Top-level chatbot
• BotVersion - Version configuration
• GenAiPlannerBundle - Reasoning engine
• GenAiPlugin - All topics
• GenAiFunction - All actions

NOT Included:

• Apex classes (deploy separately)
• Flows (deploy separately)
• Named Credentials (deploy separately)

Sync Operations

Retrieving Agents from Org

# Retrieve agent using pseudo metadata type
sf project retrieve start --metadata Agent:Customer_Support_Agent --target-org myorg

# Retrieve to specific output directory
sf project retrieve start --metadata Agent:Customer_Support_Agent --output-dir ./retrieved --target-org myorg

# Retrieve multiple agents
sf project retrieve start --metadata Agent:Support_Agent,Agent:Sales_Agent --target-org myorg

Retrieving Specific Components

# Retrieve just the bot definition
sf project retrieve start --metadata Bot:Customer_Support_Agent --target-org myorg

# Retrieve just the planner bundle
sf project retrieve start --metadata GenAiPlannerBundle:Customer_Support_Agent_Planner --target-org myorg

# Retrieve all plugins (topics)
sf project retrieve start --metadata GenAiPlugin --target-org myorg

# Retrieve all functions (actions)
sf project retrieve start --metadata GenAiFunction --target-org myorg

Deploying Agents to Org

# Deploy agent using pseudo metadata type
sf project deploy start --metadata Agent:Customer_Support_Agent --target-org myorg

# Deploy with validation only (dry run)
sf project deploy start --metadata Agent:Customer_Support_Agent --dry-run --target-org myorg

# Deploy multiple agents
sf project deploy start --metadata Agent:Support_Agent,Agent:Sales_Agent --target-org myorg

Agent Lifecycle Management

Activate Agent

Makes an agent available to users.

sf agent activate --api-name [AgentName] --target-org [alias]

Requirements:

• Agent must be published first (sf agent publish authoring-bundle)
• All Apex classes and Flows must be deployed
• default_agent_user must be a valid org user with Agentforce permissions

Post-Activation:

• Agent is immediately available to users
• Preview command can be used for testing
• Changes require deactivation first

Deactivate Agent

Deactivates an agent for modifications. Required before making changes.

sf agent deactivate --api-name [AgentName] --target-org [alias]

When Deactivation is Required:

• Adding or removing topics
• Modifying action configurations
• Changing system instructions
• Updating variable definitions

Modification Workflow

# 1. Deactivate agent
sf agent deactivate --api-name Customer_Support_Agent --target-org myorg

# 2. Make changes to Agent Script

# 3. Re-publish
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Re-activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

Agent Preview

Preview allows testing agent behavior before production deployment.

Preview Modes

Simulated Mode (Default)

sf agent preview --api-name Customer_Support_Agent --target-org myorg

• LLM simulates action responses
• No actual Apex/Flow execution
• Safe for testing - no data changes

Live Mode

sf agent preview --api-name Customer_Support_Agent --use-live-actions --target-org myorg

Requirements:

• Standard org auth (sf org login web)
• Apex classes and Flows deployed
• Agent must be active

Preview with Debug Output

sf agent preview --api-name Customer_Support_Agent --output-dir ./preview-logs --apex-debug --target-org myorg

v2.121.7+: Live preview no longer requires a Connected App. Standard org auth (sf org login web) suffices.

Full Deployment Workflows

New Agent Deployment

Complete workflow for deploying a new agent:

# 1. Deploy Apex classes (if any)
sf project deploy start --metadata ApexClass --target-org myorg

# 2. Deploy Flows
sf project deploy start --metadata Flow --target-org myorg

# 3. Validate Agent Script
sf agent validate authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Publish agent
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 5. Preview (simulated mode)
sf agent preview --api-name Customer_Support_Agent --target-org myorg

# 6. Activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

# 7. Preview (live mode - optional)
sf agent preview --api-name Customer_Support_Agent --use-live-actions --target-org myorg

Update Existing Agent

# 1. Deactivate
sf agent deactivate --api-name Customer_Support_Agent --target-org myorg

# 2. Deploy updated dependencies (if any)
sf project deploy start --metadata ApexClass,Flow --target-org myorg

# 3. Validate
sf agent validate authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Re-publish
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 5. Preview
sf agent preview --api-name Customer_Support_Agent --target-org myorg

# 6. Re-activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

Sync Between Orgs

# 1. Retrieve from source org
sf project retrieve start --metadata Agent:Customer_Support_Agent --target-org source-org

# 2. Deploy dependencies to target org first
sf project deploy start --source-dir force-app/main/default/classes --target-org target-org
sf project deploy start --source-dir force-app/main/default/flows --target-org target-org

# 3. Deploy agent metadata
sf project deploy start --metadata Agent:Customer_Support_Agent --target-org target-org

# 4. Publish agent in target org
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org target-org

# 5. Activate in target org
sf agent activate --api-name Customer_Support_Agent --target-org target-org

CI/CD Pipeline Integration

Example deployment script for CI/CD:

#!/bin/bash
# deploy-agent.sh

set -e  # Exit on error

ORG_ALIAS=$1
AGENT_NAME=$2

echo "🚀 Deploying agent: $AGENT_NAME to $ORG_ALIAS"

# Step 1: Deploy dependencies
echo "📦 Deploying Apex classes..."
sf project deploy start --metadata ApexClass --target-org $ORG_ALIAS --wait 10

echo "📦 Deploying Flows..."
sf project deploy start --metadata Flow --target-org $ORG_ALIAS --wait 10

# Step 2: Validate agent script
echo "✅ Validating Agent Script..."
sf agent validate authoring-bundle --api-name $AGENT_NAME --target-org $ORG_ALIAS

# Step 3: Check if agent exists (deactivate if needed)
echo "🔍 Checking agent status..."
if sf agent deactivate --api-name $AGENT_NAME --target-org $ORG_ALIAS 2>/dev/null; then
    echo "⏸️ Agent deactivated for update"
fi

# Step 4: Publish agent (--skip-retrieve skips metadata retrieval, faster in CI)
echo "📤 Publishing agent..."
sf agent publish authoring-bundle --api-name $AGENT_NAME --target-org $ORG_ALIAS --skip-retrieve --wait 10

# Step 5: Activate agent
echo "▶️ Activating agent..."
sf agent activate --api-name $AGENT_NAME --target-org $ORG_ALIAS

echo "✅ Agent deployment complete: $AGENT_NAME"

Usage:

./deploy-agent.sh myorg Customer_Support_Agent

Dependency Deployment Order

Critical: Dependencies must be deployed BEFORE the agent.

1. Custom Objects/Fields (sf-metadata)
   ↓
2. Apex Classes (sf-apex)
   ↓
3. Flows (sf-flow)
   ↓
4. Named Credentials (sf-integration, if external APIs)
   ↓
5. Agent Metadata (sf-ai-agentscript publish)
   ↓
6. Agent Activation

Deployment Commands by Order

# 1. Objects/Fields
sf project deploy start --metadata CustomObject,CustomField --target-org myorg

# 2. Apex
sf project deploy start --metadata ApexClass --target-org myorg

# 3. Flows
sf project deploy start --metadata Flow --target-org myorg

# 4. Named Credentials (if needed)
sf project deploy start --metadata NamedCredential --target-org myorg

# 5. Publish agent
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg

# 6. Activate
sf agent activate --api-name My_Agent --target-org myorg

Post-Deployment Validation for API Access

After deploying and activating an agent, verify it is accessible via the Agent Runtime API. Missing metadata causes silent 500 errors.

Validation Checklist

# 1. Verify GenAiPlannerBundle has plannerSurfaces
sf project retrieve start --metadata GenAiPlannerBundle --target-org myorg --output-dir ./check
grep -l "plannerSurfaces" ./check/**/*.xml
# If no results → add plannerSurfaces block (see below)

# 2. Verify BotVersion has surfacesEnabled=true
sf project retrieve start --metadata BotVersion --target-org myorg --output-dir ./check
grep "surfacesEnabled" ./check/**/*.xml
# Should show: <surfacesEnabled>true</surfacesEnabled>

# 3. Test API connectivity
curl -s -X POST "https://DOMAIN.my.salesforce.com/services/oauth2/token" \
  -d "grant_type=client_credentials&client_id=KEY&client_secret=SECRET" | jq .access_token

Fix: Add Missing plannerSurfaces

If the GenAiPlannerBundle XML is missing the plannerSurfaces block, add CustomerWebClient:

<GenAiPlannerBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- existing elements -->
    <plannerSurfaces>
        <adaptiveResponseAllowed>false</adaptiveResponseAllowed>
        <callRecordingAllowed>false</callRecordingAllowed>
        <surface>SurfaceAction__CustomerWebClient</surface>
        <surfaceType>CustomerWebClient</surfaceType>
    </plannerSurfaces>
</GenAiPlannerBundle>

Note: EinsteinAgentApiChannel surfaceType is NOT available on all orgs. Use CustomerWebClient instead — it enables both Agent Builder Preview and Agent Runtime API access. See sf-ai-agentscript Known Issue 17.

⚠️ Agent Script agents: connection messaging: in the .agent DSL ONLY generates a Messaging plannerSurface — CustomerWebClient is never auto-generated. You must manually patch it after EVERY sf agent publish authoring-bundle. See sf-ai-agentscript Known Issue 18 for the full 6-step post-publish workflow.

Fix: Add plannerSurfaces when agent is active

If the agent is active, you must deactivate before deploying:

# Deactivate → Deploy → Activate
sf agent deactivate --api-name AgentName -o TARGET_ORG
sf project deploy start --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG --json
sf agent activate --api-name AgentName -o TARGET_ORG

Fix: Enable surfacesEnabled on BotVersion

<BotVersion xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- existing elements -->
    <surfacesEnabled>true</surfacesEnabled>
</BotVersion>

Then redeploy:

sf project deploy start --metadata GenAiPlannerBundle,BotVersion --target-org myorg

Why this matters: Without CustomerWebClient plannerSurface, the Agent Builder Preview shows "Something went wrong" and the Agent Runtime API returns 500 UNKNOWN_EXCEPTION on session creation.

ISV Packaging (BotTemplate)

Use sf agent generate template to package an agent for distribution via managed packages on AppExchange.

Generate a BotTemplate

sf agent generate template \
    --agent-file force-app/main/default/bots/My_Agent/My_Agent.bot-meta.xml \
    --agent-version 1

What Gets Generated

The command generates a BotTemplate metadata type that wraps:

• Bot — Top-level agent definition
• BotVersion — Version configuration
• GenAiPlannerBundle — Reasoning engine and topic/action bindings

Packaging Workflow

1. Generate template: Run sf agent generate template as shown above
2. Include in package: Add the BotTemplate and GenAiPlannerBundle metadata to your managed package directory
3. Create package version: sf package version create --package <name> --installation-key <key> --wait 20
4. Install in subscriber org: sf package install --package <version-id> --target-org <alias> --wait 10
5. Publish agent in subscriber org: sf agent publish authoring-bundle --api-name <name> --target-org <alias>

Key Considerations

• The BotTemplate is designed for ISV distribution — it allows subscribers to install and customize the agent
• Subscribers can modify topics, actions, and instructions after installation
• The --agent-version flag specifies which BotVersion to template (typically 1 for new agents)
• The --agent-file must point to the .bot-meta.xml file in your local project

Troubleshooting

"Internal Error, try again later"

Causes:

• Invalid default_agent_user
• Dependencies not deployed
• Flow/action variable name mismatch

Solutions:

# Verify user exists
sf data query --query "SELECT Id, Username FROM User WHERE Username = 'agent@example.com'" --target-org myorg

# Deploy dependencies first
sf project deploy start --metadata ApexClass,Flow --target-org myorg

"No active agents found"

Cause: Agent not activated

Solution:

sf agent activate --api-name My_Agent --target-org myorg

"Agent must be deactivated before changes"

Cause: Trying to modify active agent

Solution:

sf agent deactivate --api-name My_Agent --target-org myorg
# Make changes
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg
sf agent activate --api-name My_Agent --target-org myorg

Deployment Fails with Missing Dependencies

Cause: Apex/Flows not deployed before agent

Solution: Follow the dependency deployment order above.

Cross-Skill Integration

Integration Pattern

# 1. sf-apex creates InvocableMethod class
# 2. sf-flow creates wrapper Flow
# 3. sf-ai-agentscript creates agent with flow:// action
# 4. sf-deploy orchestrates deployment in correct order

Command Reference

Agent-Specific Commands

Metadata Commands with Agent Pseudo Type

Management Commands

Related Documentation

• Agent Script DSL Reference
• Agent Testing Guide