SF-AI-Agentforce-ConversationDesign Skill

"Users don't fail conversations — conversations fail users."

⚡ Quick Start

1. Design your persona → Persona Design Guide
2. Architect your topics → Topic Architecture Guide
3. Write instructions → Instruction Writing Guide
4. Score your design → Quality Scorecard

1. Run the Quality Scorecard assessment
2. Review Anti-Patterns for quick wins
3. Build an Improvement Plan

📚 Document Map

Tier 1 — Start Here

Tier 2 — Design Guides

Tier 3 — Reference Resources

Tier 4 — Templates & Examples

🏆 Scoring System (120 Points)

Category Breakdown

Grade Scale

Category 1: Persona & Tone (15 points)

Category 2: Topic Architecture (20 points)

Category 3: Instruction Quality (20 points)

Category 4: Dialog Flow Design (15 points)

Category 5: Utterance Coverage (15 points)

Category 6: Escalation Design (15 points)

Category 7: Guardrails & Safety (10 points)

Category 8: Continuous Improvement (10 points)

🎭 Persona Design

Persona Components

1. Identity — Name, role, department, target audience
2. Tone Register — Casual, neutral, or formal (Agentforce setting)
3. Personality Traits — 3-5 traits that shape response style
4. Communication Style — Sentence length, vocabulary level, empathy patterns
5. Limitations — What the agent explicitly will not do
6. Messages — Welcome message and error/fallback message (≤800 chars each)

Salesforce Implementation

Agent Builder → Agent Settings → Instructions (Agent-Level)
Agent Builder → Agent Settings → Tone (Casual/Neutral/Formal)
Agent Builder → Channels → Welcome Message
Agent Builder → Channels → Error Message

Key Principle: Write persona instructions like you're training a new employee on Day 1. Focus on who they are and how they communicate, not on specific task procedures.

🏗️ Topic Architecture

Bottom-Up Design Methodology

Step 1: List ALL actions the agent needs
        ↓
Step 2: Group actions by user intent similarity
        ↓
Step 3: Write classification descriptions per group
        ↓
Step 4: Test for semantic distinctness
        ↓
Step 5: Validate with real utterances

Why bottom-up? Starting with actions (concrete capabilities) and grouping upward produces tighter, more distinct topics than starting with abstract categories and trying to fill them.

Architecture Rules

Classification Descriptions

This topic handles questions about existing order status, including
tracking information, estimated delivery dates, and order modification
requests. It does NOT handle new order placement or returns.

Order stuff

Test: Can you read two classification descriptions and immediately tell which utterance belongs to which topic? If not, they need more specificity.

✍️ Instruction Writing

The Three-Level Framework

┌─────────────────────────────────────────────────┐
│  AGENT-LEVEL INSTRUCTIONS                       │
│  Persona, global rules, limitations             │
│  Applies to: ALL topics, ALL turns              │
│  Length: 200-500 words                          │
├─────────────────────────────────────────────────┤
│  TOPIC-LEVEL INSTRUCTIONS                       │
│  Workflow logic, data gathering, decisions       │
│  Applies to: One topic only                     │
│  Length: 100-300 words per topic                │
├─────────────────────────────────────────────────┤
│  ACTION-LEVEL INSTRUCTIONS                      │
│  When/how to invoke, inputs, output handling     │
│  Applies to: One action only                    │
│  Length: 50-150 words per action                │
└─────────────────────────────────────────────────┘

Core Principles

1. Guidance Over Determinism

✅ GOOD: "When the customer seems frustrated, prioritize empathy
   and offer to escalate if the issue isn't resolved within 2-3 exchanges."

❌ BAD: "If the customer says 'this is ridiculous' OR 'I'm frustrated'
   OR 'this is unacceptable', respond with 'I understand your frustration.
   Let me connect you with a specialist.' and immediately escalate."

2. Positive Framing

✅ GOOD: "Always verify the customer's identity by asking for their
   order number or email address before accessing account details."

❌ BAD: "Don't ever access account details without first verifying
   the customer's identity. Never skip the verification step."

3. Business Principles, Not Decision Trees

✅ GOOD: "For refund requests, gather the order number and reason.
   Use the Check_Refund_Eligibility action to determine if the
   refund can be processed automatically."

❌ BAD: "If refund amount < $50 AND order date < 30 days AND
   item not in exclusion list, approve refund. If refund amount
   >= $50 OR order date >= 30 days, escalate to manager."

Rule of Thumb: If your instruction contains

if...then...else

logic with specific thresholds or calculations, it belongs in a Flow or Apex action, not in instructions.

4. Knowledge Over Hard-Coding

✅ GOOD: "Use the Search_Return_Policy action to find the applicable
   return policy before advising the customer."

❌ BAD: "Our return policy allows returns within 30 days for most items.
   Electronics have a 15-day window. Sale items are final sale.
   International orders have a 45-day window..."

🔄 Dialog Flow Patterns

The Six-Phase Conversation Lifecycle

┌──────────────┐
│  1. GREETING │  Welcome, set expectations, disclose AI nature
└──────┬───────┘
       ▼
┌──────────────────┐
│  2. CLASSIFICATION│  Route utterance to correct topic
└──────┬───────────┘
       ▼
┌──────────────────┐
│  3. GATHERING    │  Collect required information (multi-turn)
└──────┬───────────┘
       ▼
┌──────────────────┐
│  4. PROCESSING   │  Execute actions (Flow/Apex/Knowledge)
└──────┬───────────┘
       ▼
┌──────────────────┐
│  5. RESPONSE     │  Present results, confirm understanding
└──────┬───────────┘
       ▼
┌──────────────────┐
│  6. CLOSE        │  Summary, follow-up offer, farewell
└──────────────────┘

Phase Details

• Welcome message (configured in Agent Builder, ≤800 chars)
• AI disclosure: "I'm an AI assistant for [Company]"
• Scope setting: "I can help with [X], [Y], and [Z]"

• Automatic via topic classification descriptions
• Disambiguation if confidence is low: "I can help with [A] or [B] — which one?"
• Out-of-scope handling: Acknowledge → Redirect or escalate

• Ask for one piece of information at a time (progressive disclosure)
• Confirm understanding: "So you're looking for [X], correct?"
• Handle corrections gracefully: "Let me update that"

• Execute actions (Flow invocations, Apex calls, Knowledge lookups)
• Provide wait indicators for long operations
• Handle action failures with user-friendly messages

• Present results clearly (structured when appropriate)
• Confirm the answer addresses their question
• Offer related assistance: "Is there anything else about your order?"

• Summarize what was accomplished
• Offer follow-up: "Anything else I can help with?"
• Farewell appropriate to tone register

Progressive Disclosure

✅ GOOD (2 choices):
"I can help you track an existing order or start a return.
 Which would you like?"

❌ BAD (5+ choices):
"I can track orders, start returns, modify orders, check
 inventory, update shipping address, change payment method,
 or cancel orders. What do you need?"

Rule: Maximum 2-3 choices per turn. If more options exist, group them or ask a qualifying question first.

📝 Utterance Design

Utterance Categories

Coverage Targets

Building an Utterance Library

1. Start with real data — Pull from CRM cases, chat logs, support tickets
2. Brainstorm synonyms — How would different users phrase the same request?
3. Add edge cases — Multi-intent, typos, incomplete sentences
4. Include adversarial — Prompt injection, manipulation, out-of-character requests
5. Test in Testing Center — CSV upload, verify classification accuracy
6. Iterate — Add utterances that failed, adjust classification descriptions

🚨 Escalation Design

Escalation Trigger Catalog

Agentforce Escalation Implementation

Agent Builder → Topics → Escalation (pre-built)
  ├── Classification: Automatic (always available)
  ├── Routing: Omni-Channel Queue or Skill-based
  └── Context: Conversation transcript passed to agent

Context Handoff

1. Conversation transcript — Full history (automatic in Agentforce)
2. Customer identity — Verified account/contact info
3. Issue summary — What the customer needs (agent-generated)
4. Actions taken — What the agent already tried
5. Escalation reason — Why the agent is escalating

🛡️ Guardrails & Safety

The Four-Layer Guardrail Model

┌─────────────────────────────────────────────┐
│  LAYER 1: Einstein Trust Layer (Platform)   │
│  Toxicity detection, PII masking, prompt    │
│  injection defense — automatic, always on   │
├─────────────────────────────────────────────┤
│  LAYER 2: Topic Classification (Design)     │
│  Scope boundaries, out-of-scope rejection,  │
│  topic routing as first line of defense     │
├─────────────────────────────────────────────┤
│  LAYER 3: Instructions (Behavioral)         │
│  Explicit limitations, persona constraints, │
│  "do not provide legal/medical advice"      │
├─────────────────────────────────────────────┤
│  LAYER 4: Flow/Apex Logic (Deterministic)   │
│  Business rule enforcement, data validation,│
│  hard limits, approval gates                │
└─────────────────────────────────────────────┘

Layer Responsibilities

Critical Rule: Never rely on instructions alone for safety-critical decisions. Instructions are probabilistic (LLM-based). Business rules, financial limits, and compliance checks MUST be in Flow or Apex.

📊 Quality Assessment

Assessment Process

1. Gather artifacts — Collect agent configuration, instructions, topic definitions, test results
2. Score each category — Use the detailed criteria in the scorecard
3. Calculate total — Sum all category scores
4. Assign grade — Map total to A/B/C/D/F
5. Identify gaps — Categories scoring below 70% of their maximum
6. Build improvement plan — Prioritize by impact and effort

Quick Health Check

⚠️ Anti-Patterns

The Top 10

🔁 Continuous Improvement

The Iteration Cycle

    ┌─────────┐
    │ MONITOR │  Track KPIs, review dashboards
    └────┬────┘
         ▼
    ┌─────────┐
    │ ANALYZE │  Identify misrouted utterances, low-CSAT sessions
    └────┬────┘
         ▼
    ┌─────────┐
    │   FIX   │  Update instructions, adjust classifications, add actions
    └────┬────┘
         ▼
    ┌─────────┐
    │ RETEST  │  Run regression tests, add new test cases
    └────┬────┘
         ▼
    ┌─────────┐
    │ DEPLOY  │  Push changes, monitor for improvement
    └────┬────┘
         │
         └──────→ (back to MONITOR)

Key Performance Indicators

Utterance Analysis Process

1. Export unmatched utterances — Pull from Agentforce analytics
2. Categorize — New intent? Phrasing gap? True out-of-scope?
3. Update — Add new utterances to library, adjust classifications if needed
4. Test — Verify changes don't break existing routing
5. Deploy — Push updated agent configuration
6. Schedule — Repeat weekly for first month, then bi-weekly

🔗 Chain Integration

sf-ai-agentforce-conversationdesign   ← YOU ARE HERE
        │
        ▼
   sf-metadata  →  sf-apex  →  sf-flow  →  sf-deploy
        │                                      │
        ▼                                      ▼
   sf-ai-agentscript              sf-ai-agentforce-testing
        │
        ▼
   sf-deploy  →  sf-ai-agentforce-testing

Handoff Points

📎 Credits & References

• Google Conversation Design Guidelines
• IBM Natural Conversation Framework
• Red Hat PatternFly AI Design System
• Salesforce Conversational AI Design Guide
• Salesforce Architect: Agentic Patterns & Taxonomy