SF-AI-Agentforce-ConversationDesign Skill

“Users don’t fail conversations — conversations fail users.”

Conversation design is the discipline of crafting agent interactions that feel natural, resolve issues efficiently, and gracefully handle the unexpected. This skill brings structured conversation design methodology to Salesforce Agentforce, combining industry frameworks (Google, IBM, PatternFly) with Salesforce-specific implementation patterns.

⚡ Quick Start

New agent? Start here:

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

Existing agent needs improvement? Start here:

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

A persona defines your agent’s personality, communication style, and behavioral constraints. It’s the foundation that ensures consistent, brand-aligned interactions across all conversations.

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

The persona lives primarily in agent-level instructions. These instructions apply to every topic and every turn — they’re the global behavioral baseline.

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.

📖 Deep Dive: Persona Design Guide | Template: Persona Document | Example: Service Agent Persona

🏗️ Topic Architecture

Topics are the organizational backbone of an Agentforce agent. Each topic groups related actions under a classification description that the agent uses to route user utterances.

Bottom-Up Design Methodology

The most reliable way to design topics:

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

Classification descriptions are the single most important text in your agent design. They determine how accurately utterances route to topics.

Good classification description:

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.

Bad classification description:

Order stuff

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

📖 Deep Dive: Topic Architecture Guide | Template: Topic Architecture | Example: Retail Topic Architecture

✍️ Instruction Writing

Instructions operate at three levels, each with a different scope and purpose:

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

Instructions should guide the agent’s reasoning, not hard-code every decision.

✅ 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

Tell the agent what TO do, not what NOT to do.

✅ 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

Train like a human employee — give principles, not scripts.

✅ 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

Use Knowledge actions (RAG) for policies, not inline instructions.

✅ 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..."

📖 Deep Dive: Instruction Writing Guide

🔄 Dialog Flow Patterns

Every conversation follows a six-phase lifecycle. Well-designed agents handle each phase intentionally.

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

Phase 1 — Greeting:

• 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]”

Phase 2 — Classification:

• 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

Phase 3 — Gathering:

• 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”

Phase 4 — Processing:

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

Phase 5 — Response:

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

Phase 6 — Close:

• 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

Utterances are the test cases for your topic architecture. A comprehensive utterance library validates that classification descriptions route correctly.

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

📖 Template: Utterance Library

🚨 Escalation Design

Escalation is not failure — it’s a safety net that ensures customers always reach resolution. Well-designed escalation maintains context and routes efficiently.

Escalation Trigger Catalog

Agentforce Escalation Implementation

Agentforce provides a pre-built Escalation Topic that routes to human agents via Omni-Channel:

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

When escalating, pass:

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

📖 Deep Dive: Escalation Patterns | Template: Escalation Matrix | Example: Healthcare Escalation

🛡️ Guardrails & Safety

Safety in Agentforce operates through four layers, from platform-level to code-level:

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.

📖 Deep Dive: Guardrail Hierarchy

📊 Quality Assessment

Use the Quality Scorecard to assess any Agentforce agent against the 120-point rubric.

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

Before a full assessment, answer these five questions:

If any red flag appears, start your improvement plan there.

⚠️ Anti-Patterns

Common conversation design mistakes that reduce agent quality:

The Top 10

📖 Deep Dive: Anti-Patterns — Full examples with before/after fixes for each pattern.

🔁 Continuous Improvement

Conversation design is never “done.” Production usage reveals gaps that testing cannot fully predict.

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

📖 Deep Dive: Quality Metrics | Template: Improvement Plan

🔗 Chain Integration

This skill is the first step in the Agentforce development chain:

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

See CREDITS.md for full attribution.