mirror of https://github.com/forcedotcom/afv-library.git synced 2026-07-31 04:01:24 +08:00

GitHub Action ae792239f2 feat: Release 2 new skills: platform-models-api-configure, platform-policy-rule-generate @W-23396600@

2026-07-10 17:19:21 +00:00

20 KiB

Raw Blame History

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:

agentforce-generate - Agent authoring, publishing, Agent Builder, and Prompt Builder
platform-metadata-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 a specific BotVersion along with the bot definition
sf project retrieve start \
  --metadata Bot:Customer_Support_Agent \
  --metadata BotVersion:Customer_Support_Agent.v3 \
  --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

Versioned retrieve note: Current SF CLI releases correctly retrieve the specific BotVersion you request instead of always pulling only the latest version.

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.

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

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name [AgentName] --version [N] --target-org [alias] --json

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

Activation notes:

--version [N] maps to the vN suffix in BotVersion metadata
Omitting --version triggers interactive version selection
Using --json without --version activates the latest agent version
For CI/CD and reproducible rollouts, prefer --version [N] --json

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.

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

# Script-friendly deactivation
sf agent deactivate --api-name [AgentName] --target-org [alias] --json

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
AGENT_VERSION=$3

echo "🚀 Deploying agent: $AGENT_NAME to $ORG_ALIAS (version: $AGENT_VERSION)"

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

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

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

# 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 --json 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 --json

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

echo "✅ Agent deployment complete: $AGENT_NAME"

Usage:

./deploy-agent.sh myorg Customer_Support_Agent 4

Pass the BotVersion number you intend to activate as the third argument.

Dependency Deployment Order

Critical: Dependencies must be deployed BEFORE the agent.

1. Custom Objects/Fields (platform-custom-object-generate, platform-custom-field-generate)
   ↓
2. Apex Classes (platform-apex-generate)
   ↓
3. Flows (automation-flow-generate)
   ↓
4. Named Credentials (integration-connectivity-generate, if external APIs)
   ↓
5. Agent Metadata (agentforce-generate 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.

⚠️ 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 the post-publish workflow in agentforce-generate.

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 --json
sf project deploy start --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG --json
sf agent activate --api-name AgentName --version NN -o TARGET_ORG --json

Use the same NN value from the planner bundle version you just patched so activation is deterministic.

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 \
    --output-dir my-package \
    --source-org my-scratch-org \
    --json

Important: This command packages Bot / BotVersion-based agents. It does not package Agent Script .agent authoring bundles.

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

Generate template: Run sf agent generate template as shown above
Include in package: Add the BotTemplate and GenAiPlannerBundle metadata to your managed package directory
Create package version: sf package version create --package <name> --installation-key <key> --wait 20
Install in subscriber org: sf package install --package <version-id> --target-org <alias> --wait 10
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
--source-org must be a namespaced scratch org that contains the source agent
Agent Script .agent bundles currently need a different rollout path; use source-driven publish workflows instead of sf agent generate template

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