025 Agent Deployment Guide 4ea8468e

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.

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