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
echo "📤 Publishing agent..."
sf agent publish authoring-bundle --api-name $AGENT_NAME --target-org $ORG_ALIAS --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

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