How do I install the Agentforce Agent Deployment Guide skill?

Run npx skillmds@latest add tools-only/agentforce-agent-deployment-guide-4 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Agentforce Agent Deployment Guide safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Agentforce Agent Deployment Guide?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Agentforce Agent Deployment Guide free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Agentforce Agent Deployment Guide?

tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Agentforce Agent Deployment Guide by tools-only

Name: Agentforce Agent Deployment Guide
Author: tools-only

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 Type	Description	Example API Name
`Bot`	Top-level chatbot definition	`Customer_Support_Agent`
`BotVersion`	Version configuration	`Customer_Support_Agent.v1`
`GenAiPlannerBundle`	Reasoning engine (LLM config)	`Customer_Support_Agent_Planner`
`GenAiPlugin`	Topic definition	`Order_Management_Plugin`
`GenAiFunction`	Action definition	`Get_Order_Status_Function`

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

Mode	Command	Use When
Simulated	`sf agent preview --api-name X`	Testing logic, Apex/Flows not ready
Live	`sf agent preview --api-name X --use-live-actions`	Integration testing with real data

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

From Skill	To Skill	Purpose
sf-ai-agentscript	sf-deploy	Publish and activate agents
sf-apex	sf-deploy	Deploy Apex before agent
sf-flow	sf-deploy	Deploy Flows before agent
sf-integration	sf-deploy	Deploy Named Credentials for external APIs

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

Command	Description
`sf agent publish authoring-bundle --api-name X`	Publish authoring bundle
`sf agent publish authoring-bundle --api-name X --skip-retrieve`	Publish without retrieving from org (CI/CD)
`sf agent activate --api-name X`	Activate published agent
`sf agent deactivate --api-name X`	Deactivate agent for changes
`sf agent preview --api-name X`	Preview agent behavior
`sf agent validate authoring-bundle --api-name X`	Validate Agent Script syntax

Metadata Commands with Agent Pseudo Type

Command	Description
`sf project retrieve start --metadata Agent:X`	Retrieve agent + components
`sf project deploy start --metadata Agent:X`	Deploy agent metadata
`sf project retrieve start --metadata Bot:X`	Retrieve bot definition only
`sf project retrieve start --metadata GenAiPlannerBundle:X`	Retrieve planner bundle
`sf project retrieve start --metadata GenAiPlugin`	Retrieve all plugins
`sf project retrieve start --metadata GenAiFunction`	Retrieve all functions

Management Commands

Command	Description
`sf org open agent --api-name X`	Open agent in Agentforce Builder
`sf org open authoring-bundle`	Open Agentforce Studio list view (v2.121.7+)
`sf org list metadata --metadata-type Bot`	List bots in org
`sf org list metadata --metadata-type GenAiPlannerBundle`	List planner bundles

Agentforce Agent Deployment Guide

File contents

Agentforce Agent Deployment Guide

Overview

Agent Metadata Types

Metadata Hierarchy

Agent Pseudo Metadata Type

Using the Agent Pseudo Type

What Gets Synced

Sync Operations

Retrieving Agents from Org

Retrieving Specific Components

Deploying Agents to Org

Agent Lifecycle Management

Activate Agent

Deactivate Agent

Modification Workflow

Agent Preview

Preview Modes

Simulated Mode (Default)

Live Mode

Preview with Debug Output

Full Deployment Workflows

New Agent Deployment

Update Existing Agent

Sync Between Orgs

CI/CD Pipeline Integration

Dependency Deployment Order

Deployment Commands by Order

Post-Deployment Validation for API Access

Validation Checklist

Fix: Add Missing plannerSurfaces

Fix: Add plannerSurfaces when agent is active

Fix: Enable surfacesEnabled on BotVersion

Troubleshooting

"Internal Error, try again later"

"No active agents found"

"Agent must be deactivated before changes"

Deployment Fails with Missing Dependencies

Cross-Skill Integration

Integration Pattern

Command Reference

Agent-Specific Commands

Metadata Commands with Agent Pseudo Type

Management Commands

Related Documentation

Related skills

Frequently asked questions

How do I install the Agentforce Agent Deployment Guide skill?

What does the Agentforce Agent Deployment Guide skill do?

Is Agentforce Agent Deployment Guide safe to use?

Which AI agents work with Agentforce Agent Deployment Guide?

Is Agentforce Agent Deployment Guide free to use?

Who published Agentforce Agent Deployment Guide?