Skip to content

forcedotcom/sf-skills / skills/sales-agentforce-pipeline-management-configure

sales-agentforce-pipeline-management-configure

Verified

Use to configure, set up, or repair the Sales Management agent and Agentforce Pipeline Management in a Salesforce org. Automates metadata creation for flows, prompt templates, permission sets, and data source configuration. TRIGGER when: user wants to enable Pipeline Management, configure Sales pipeline features, set up the Sales Management agent for opportunity field updates (including autonomous updates), connect enabled data sources like Einstein Conversation Insights or Einstein Activity Capture, customize opportunity stage descriptions, configure post-meeting suggestions, verify or audit configuration status, fix partially configured orgs, or troubleshoot Pipeline Management metadata issues. DO NOT TRIGGER when: user wants to build a custom agent (use agentforce-generate), configure general Agentforce tracing (use platform-tracing-agentforce-configure), work with non-Sales agents, or enable Einstein Conversation Insights or Einstein Activity Capture from scratch (provisioning is out of scope).

FileKindSize
SKILL.mdskill md29.0 KB
assets/field-completion-template.genAiPromptTemplate-meta.xmlconfig8.6 KB
assets/pipeline_management_flow.flow-meta.xmlconfig22.9 KB
assets/sales_management_agent.agentother211.7 KB
assets/sales_management_agent.bundle-meta.xmlconfig163 B
assets/sfdx-project.jsonconfig254 B
assets/stage-descriptions/bant.txtmarkdown2.7 KB
assets/stage-descriptions/meddic.txtmarkdown2.9 KB
assets/stage-descriptions/spiced.txtmarkdown2.9 KB
examples/custom-prompt-instructions.mdmarkdown10.0 KB
references/admin-communication.mdmarkdown14.6 KB
references/agent-creation.mdmarkdown22.5 KB
references/auth-and-cli.mdmarkdown6.7 KB
references/automation-matrix.mdmarkdown2.2 KB
references/autonomous-updates.mdmarkdown8.4 KB
references/canonical-agent-path.mdmarkdown6.9 KB
references/data-sources.mdmarkdown6.6 KB
references/field-completion-prompt-template.mdmarkdown6.4 KB
references/field-completion-prompts.mdmarkdown10.4 KB
references/flags.mdmarkdown3.2 KB
references/flow-clone-from-template.mdmarkdown19.5 KB
references/metadata-inventory.mdmarkdown17.1 KB
references/opportunity-stages.mdmarkdown11.9 KB
references/repair-diagnostics.mdmarkdown14.1 KB
references/setup-order.mdmarkdown12.6 KB
references/soap-api-enablement.mdmarkdown21.7 KB
scripts/CHANGES.mdmarkdown5.6 KB
scripts/README.mdmarkdown3.1 KB
scripts/add-field-suggestion.shexecutablescript35.5 KB
scripts/create-agent.shexecutablescript13.2 KB
scripts/create-flow.shexecutablescript8.5 KB
scripts/define-agent-access.shexecutablescript21.2 KB
scripts/deploy-settings.shexecutablescript1.9 KB
scripts/enable-deal-agent.shexecutablescript10.0 KB
scripts/enable-prerequisites.shexecutablescript22.9 KB
scripts/flow-debug-and-verify.shexecutablescript18.4 KB
scripts/retrieve-settings.shexecutablescript5.7 KB
scripts/setup-all.shscript146.6 KB
scripts/shared/agent-bundle-publish.shscript6.7 KB
scripts/shared/agent-detection.shscript9.7 KB
scripts/shared/flow-builder.shscript9.5 KB
scripts/shared/psg.shscript1.9 KB
scripts/shared/soap.shscript5.6 KB
scripts/shared/stage-descriptions.shscript23.3 KB
scripts/shared/test-opp.shscript9.6 KB
scripts/verify-all.shexecutablescript26.0 KB
scripts/verify-prompt-generation.shexecutablescript13.8 KB

scripts/create-agent.sh

View on GitHub
#!/bin/bash

# Verify and ensure Pipeline Management agent is functional.
#
# CRITICAL: BotDefinition:SalesAgent is REQUIRED for a functional Pipeline Management agent.
# Users need an interactive Sales Agent they can chat with, which requires the BotDefinition.
# The agent user + PSG provision the backend identity, but without the BotDefinition,
# users CANNOT interact with the Sales Agent via chat/conversation interface.
#
# This script ensures:
#   Step 1: Agent user exists with SalesManagementAgentUserPsg assigned
#   Step 2: BotDefinition:SalesAgent is created and activated (via authoring bundle)
#   Step 3: Both are verified functional (backend + user-facing)
#
# If the agent user exists but BotDefinition is missing, the script CREATES it.
# If BotDefinition creation fails, the script EXITS 1 (setup incomplete).
#
# Usage: ./create-agent.sh <org-alias>

set -euo pipefail

# sf CLI can emit ANSI color codes inside --json stdout, breaking jq parsing.
# 2>/dev/null only strips stderr; these env vars are the reliable fix (see PM notes).
export NO_COLOR=1
export FORCE_COLOR=0

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Source shared library
source "$SCRIPT_DIR/shared/agent-bundle-publish.sh"

# Define Agent Access (W-23242378) so human users holding SalesManagementUserPsg
# can launch the agent. Idempotent; exits gracefully if no active bot exists.
define_agent_access() {
  local org="$1"
  if [[ -f "$SCRIPT_DIR/define-agent-access.sh" ]]; then
    echo ""
    echo "=== Defining Agent Access (W-23242378) ==="
    local rc=0
    bash "$SCRIPT_DIR/define-agent-access.sh" "$org" || rc=$?
    if [[ $rc -ne 0 ]]; then
      echo "  Warning: Agent Access definition failed (exit $rc) — see above"
      return $rc
    fi
  fi
}

ORG_ALIAS="${1:-}"

if [[ -z "$ORG_ALIAS" ]]; then
  echo "Error: Missing org alias"
  echo "Usage: $0 <org-alias>"
  exit 1
fi

echo "Verifying Pipeline Management agent setup"
echo ""

# --- Step 1: Check functional indicators (agent user + PSG) ---
echo "=== Step 1: Checking agent user (primary functional indicator) ==="
AGENT_USER=$(sf data query \
  --query "SELECT Id, Username FROM User WHERE Username LIKE '%salesmanagementagentuser%'" \
  --target-org "$ORG_ALIAS" \
  --json 2>/dev/null | jq -r '.result.records[0] // empty' 2>/dev/null || echo "")

if [[ -n "$AGENT_USER" ]]; then
  AGENT_USERNAME=$(echo "$AGENT_USER" | jq -r '.Username')
  AGENT_USER_ID=$(echo "$AGENT_USER" | jq -r '.Id')
  echo "  Agent user found: $AGENT_USERNAME"
  echo ""

  # Check PSG assignment
  PSG_ASSIGNED=$(sf data query \
    --query "SELECT PermissionSetGroup.DeveloperName FROM PermissionSetAssignment WHERE AssigneeId = '${AGENT_USER_ID}' AND PermissionSetGroup.DeveloperName = 'SalesManagementAgentUserPsg'" \
    --target-org "$ORG_ALIAS" \
    --json 2>/dev/null | jq -r '.result.records[0] // empty' 2>/dev/null || echo "")

  if [[ -n "$PSG_ASSIGNED" ]]; then
    echo "  PSG assigned: SalesManagementAgentUserPsg ✓"
  else
    echo "  Warning: SalesManagementAgentUserPsg not assigned — attempting assignment..."
    PSG_ID=$(sf data query \
      --query "SELECT Id FROM PermissionSetGroup WHERE DeveloperName = 'SalesManagementAgentUserPsg'" \
      --target-org "$ORG_ALIAS" \
      --json 2>/dev/null | jq -r '.result.records[0].Id // empty')
    if [[ -n "$PSG_ID" ]]; then
      sf data create record --sobject PermissionSetAssignment \
        --values "AssigneeId='${AGENT_USER_ID}' PermissionSetGroupId='${PSG_ID}'" \
        --target-org "$ORG_ALIAS" --json 2>/dev/null >/dev/null \
        && echo "  PSG assigned successfully ✓" \
        || echo "  Assignment failed (may already be assigned)"
    fi
  fi
  echo ""

  # Determine architecture — match the bot by AgentTemplate (the field the
  # scheduled flow uses), not by hardcoded DeveloperName.
  echo "=== Architecture Detection ==="
  EXISTING_BOT=$(pm_bot_developer_name "$ORG_ALIAS")

  if [[ -n "$EXISTING_BOT" ]]; then
    echo "  Architecture: Standalone Bot (BotDefinition:$EXISTING_BOT matched by AgentTemplate)"
    echo ""

    # A BotDefinition can exist yet have no ACTIVE version — the state
    # auto-provisioning leaves it in. Without an active version the scheduled
    # flow never adds the agent user to opportunity teams (no suggestions) and
    # Agent Access can't be defined. Activate the latest version if needed.
    BOT_ACTIVE_COUNT=$(pm_bot_active_version_count "$ORG_ALIAS")
    if [[ "$BOT_ACTIVE_COUNT" -ge 1 ]]; then
      echo "  BotVersion: active ✓"
    else
      echo "  BotVersion: no active version — activating (auto-provisioned bots land Inactive)..."
      if ! activate_pm_bot_if_inactive "$ORG_ALIAS"; then
        echo ""
        echo "  BLOCKER: BotDefinition:$EXISTING_BOT exists but has no active version and activation failed."
        echo "  The scheduled flow will not generate suggestions until the agent is active."
        echo "    Resolve via Setup → Agents → $EXISTING_BOT → activate, then re-run: $0 $ORG_ALIAS"
        exit 1
      fi
    fi

    echo ""
    echo "Agent setup is FUNCTIONAL."
    echo "  - Agent user: $AGENT_USERNAME"
    echo "  - PSG: SalesManagementAgentUserPsg"
    echo "  - BotDefinition: $EXISTING_BOT (active)"
    echo "  - Schedule-triggered flow will run as this user"
    echo ""
    echo "No further agent creation/deployment needed."
    define_agent_access "$ORG_ALIAS"
    exit $?
  else
    echo "  Architecture: Platform Copilot (no standalone BotDefinition found)"
    echo "  Attempting to create Sales Agent BotDefinition for user interaction..."
    echo ""

    # Use shared library function to publish and activate agent
    if publish_and_activate_agent "$ORG_ALIAS" "exit" "plain"; then
      echo ""
      echo "Agent setup is COMPLETE."
      echo "  - Agent user: $AGENT_USERNAME"
      echo "  - PSG: SalesManagementAgentUserPsg"
      echo "  - BotDefinition: ${AGENT_API_NAME:-SalesAgent} (ACTIVE, version $AGENT_VERSION)"
      echo "  - Schedule-triggered flow will run as this user"
      define_agent_access "$ORG_ALIAS"
      exit $?
    fi
    # If function returned non-zero, it already exited (on-error="exit")
  fi
fi

# --- Step 2: No agent user found — need remediation ---
echo "  Agent user NOT found."
echo ""
echo "=== Step 2: Attempting SOAP toggle to re-provision agent user + PSGs ==="
echo "  (The toggle re-creates the agent user and permission set groups only."
echo "   It does NOT create BotDefinition:SalesAgent — that comes from the bundle"
echo "   publish in Step 3 below.)"

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
AUTH_INFO=$(sf org display --target-org "$ORG_ALIAS" --json 2>/dev/null)
ACCESS_TOKEN=$(echo "$AUTH_INFO" | jq -r '.result.accessToken')
INSTANCE_URL=$(echo "$AUTH_INFO" | jq -r '.result.instanceUrl')

# Newer CLI versions redact accessToken — use show-access-token fallback
if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" || "$ACCESS_TOKEN" == *"REDACTED"* ]]; then
  ACCESS_TOKEN=$(echo "y" | sf org auth show-access-token --target-org "$ORG_ALIAS" --no-prompt --json 2>/dev/null | jq -r '.result.accessToken // empty')
fi

if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" ]]; then
  echo "Error: Could not retrieve org credentials. Is the org authenticated?"
  exit 1
fi

# Pre-check: Is org in "partially enabled" state (PSGs exist but enableDealAgent=false)?
# In that state, the toggle is harmful — disable may succeed but re-enable will fail.
PM_READ=$(curl -s "${INSTANCE_URL}/services/Soap/m/64.0" \
  -H "Content-Type: text/xml; charset=UTF-8" \
  -H "SOAPAction: readMetadata" \
  -d "<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
<soapenv:Header><met:SessionHeader><met:sessionId>${ACCESS_TOKEN}</met:sessionId></met:SessionHeader></soapenv:Header>
<soapenv:Body><met:readMetadata><met:type>SalesDealAgentSettings</met:type><met:fullNames>SalesDealAgent</met:fullNames></met:readMetadata></soapenv:Body>
</soapenv:Envelope>" 2>/dev/null | grep -o "<enableDealAgent>[^<]*" | grep -o "true\|false" || echo "")

# PSG existence does NOT count as a partial signal — SalesManagementUserPsg /
# SalesManagementAgentUserPsg ship with the Agentforce-for-Sales license and exist
# in never-configured orgs. The real partial signals (with enableDealAgent=false)
# are a cloned scheduled flow or a PM BotDefinition. (The agent user was already
# ruled out in Step 1 above.)
PM_FLOW_EXISTS=$(pm_flow_clone_exists "$ORG_ALIAS")
PM_BOT_EXISTS=$(pm_bot_count "$ORG_ALIAS")

if [[ "$PM_READ" != "true" && ( "${PM_FLOW_EXISTS:-0}" -ge 1 || "${PM_BOT_EXISTS:-0}" -ge 1 ) ]]; then
  echo "Detected partial-enablement state: enableDealAgent reads false but PM components exist (flow=$PM_FLOW_EXISTS bot=$PM_BOT_EXISTS)."
  echo ""
  echo "  The SOAP toggle is NOT safe in this state (re-enable may fail mid-provisioning)."
  echo "  This org was likely provisioned via org template."
  echo ""
  echo "  To resolve:"
  echo "    1. Open: ${INSTANCE_URL}/lightning/setup/PipelineManagement/home"
  echo "    2. Enable Pipeline Management in the Setup UI"
  echo "    3. Wait 2-5 minutes for agent user provisioning"
  echo "    4. Re-run this script"
  exit 0
fi

echo "  Using SOAP toggle to re-provision agent user + PSGs (NOT the BotDefinition)..."
echo "  WARNING: This will temporarily disable Pipeline Management (~40 seconds)."
echo ""

# Disable Pipeline Management
echo "  Disabling Pipeline Management..."
DISABLE_RESPONSE=$(curl -s -X POST "${INSTANCE_URL}/services/Soap/m/64.0" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: update" \
  -d "<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
<soapenv:Header><met:SessionHeader><met:sessionId>${ACCESS_TOKEN}</met:sessionId></met:SessionHeader></soapenv:Header>
<soapenv:Body><met:updateMetadata>
  <met:metadata xsi:type='met:SalesDealAgentSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
    <met:fullName>SalesDealAgent</met:fullName>
    <met:enableDealAgent>false</met:enableDealAgent>
  </met:metadata>
</met:updateMetadata></soapenv:Body>
</soapenv:Envelope>")

if echo "$DISABLE_RESPONSE" | grep -q "<success>true</success>"; then
  echo "  Disabled successfully. Waiting 10 seconds..."
  sleep 10

  # Re-enable Pipeline Management
  echo "  Re-enabling Pipeline Management..."
  ENABLE_RESPONSE=$(curl -s -X POST "${INSTANCE_URL}/services/Soap/m/64.0" \
    -H "Content-Type: text/xml; charset=utf-8" \
    -H "SOAPAction: update" \
    -d "<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
<soapenv:Header><met:SessionHeader><met:sessionId>${ACCESS_TOKEN}</met:sessionId></met:SessionHeader></soapenv:Header>
<soapenv:Body><met:updateMetadata>
  <met:metadata xsi:type='met:SalesDealAgentSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
    <met:fullName>SalesDealAgent</met:fullName>
    <met:enableDealAgent>true</met:enableDealAgent>
    <met:enableDealAgentAutoApproveAllTasks>false</met:enableDealAgentAutoApproveAllTasks>
  </met:metadata>
</met:updateMetadata></soapenv:Body>
</soapenv:Envelope>")

  if echo "$ENABLE_RESPONSE" | grep -q "<success>true</success>"; then
    echo "  Re-enabled successfully. Waiting 30 seconds for provisioning..."
    sleep 30
  else
    echo "  Error: Failed to re-enable Pipeline Management"
    echo "$ENABLE_RESPONSE" | grep -o '<message>[^<]*</message>' | sed 's/<[^>]*>//g' | head -1 || true
    exit 1
  fi
else
  ERR_MSG=$(echo "$DISABLE_RESPONSE" | grep -o '<message>[^<]*</message>' | sed 's/<[^>]*>//g' | head -1 || echo "unknown error")
  echo "  SOAP toggle failed: $ERR_MSG"
  echo ""
fi

# Check if agent user was provisioned
AGENT_USER_CHECK=$(sf data query \
  --query "SELECT Id, Username FROM User WHERE Username LIKE '%salesmanagementagentuser%'" \
  --target-org "$ORG_ALIAS" \
  --json 2>/dev/null | jq -r '.result.records[0].Username // empty' 2>/dev/null || echo "")

if [[ -n "$AGENT_USER_CHECK" ]]; then
  echo ""
  echo "  Agent user provisioned: $AGENT_USER_CHECK"
  echo "  BotDefinition:SalesAgent is still missing — the toggle does not create it."
  echo "  Proceeding to Step 3 to publish the authoring bundle."
fi

# --- Step 3: Last resort — authoring bundle deployment ---
echo ""
echo "=== Step 3: Attempting authoring bundle deployment (last resort) ==="

# Use shared library function with return-on-error behavior
if publish_and_activate_agent "$ORG_ALIAS" "return" "plain"; then
  echo "  Agent deployed and activated via authoring bundle"
  define_agent_access "$ORG_ALIAS"
  exit $?
else
  echo "  Authoring bundle publish/activate failed"
fi

# --- All approaches failed ---
echo ""
echo "=== BLOCKER: Agent provisioning failed ==="
echo ""
echo "  No agent user was created via any automated method."
echo "  Suggestions cannot generate without the agent user."
echo ""
echo "  Manual resolution:"
echo "    1. Open: ${INSTANCE_URL}/lightning/setup/PipelineManagement/home"
echo "    2. Disable Pipeline Management, wait 30 seconds, re-enable"
echo "    3. Wait 2-5 minutes for agent user provisioning"
echo "    4. Re-run: $0 $ORG_ALIAS"
exit 1
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall