@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/references/agent-topic-map-diagrams.md

@@ -0,0 +1,323 @@
+# Agent Topic Map Diagrams Reference
+
+## Table of Contents
+
+- [Purpose and Context](#purpose-and-context)
+- [Fundamental Structure Rules](#fundamental-structure-rules)
+- [Node Types and Agent Script Elements](#node-types-and-agent-script-elements)
+- [Topic Map Patterns](#topic-map-patterns)
+- [Complete Example: Local_Info_Agent](#complete-example-local_info_agent)
+- [Validation Checklist](#validation-checklist)
+- [Anti-patterns](#anti-patterns)
+
+---
+
+## Purpose and Context
+
+A Topic Map diagram is a Mermaid flowchart that visualizes an agent's topic graph structure. It shows the architecture of an agent before implementation, displaying:
+
+- The start_agent topic_selector entry point
+- All topics in the agent
+- Topic transitions and routing logic
+- Action calls within topics (with backing type: Apex, Prompt Template, Flow)
+- Gating conditions (available_when expressions)
+- Variable state changes
+- Escalation and off-topic handling
+- Conditional instructions based on variable values
+
+Topic Map diagrams are the primary visual deliverable in an Agent Spec (design document) and serve both specification and comprehension purposes.
+
+---
+
+## Fundamental Structure Rules
+
+### Graph Orientation
+
+- ALWAYS use `graph TD` (Top-Down orientation)
+- Start with start_agent topic_selector at the top
+- Topics flow downward from the selector
+- Never use other orientations
+
+### Node Identification
+
+- Use sequential capital letters (A, B, C, ...) for node IDs
+- Start with `A` for start_agent
+- Increment sequentially through topics and decisions
+- Use descriptive labels within brackets
+
+### Flow Direction
+
+- Primary flow moves top-to-bottom
+- Use `-->` for standard transitions
+- Label decision branches with `|Label|` syntax
+- Separate paths for different topics
+
+---
+
+## Node Types and Agent Script Elements
+
+### Start Agent Topic Selector Node
+
+Format: `[start_agent<br/>topic_selector]`
+
+Represents the entry point where user input is evaluated and routed to appropriate topics.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[start_agent<br/>topic_selector]
+```
+
+### Topic Nodes
+
+Format: `[topic_name<br/>Topic]`
+
+Represents a topic within the agent.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[start_agent<br/>topic_selector]
+    B[order_status<br/>Topic]
+    C[billing<br/>Topic]
+```
+
+### Action Call Nodes
+
+Format: `[Call action_name<br/>backing: Type]`
+
+Backing types: Apex, Prompt Template, Flow
+
+Example: `[Call check_weather<br/>backing: Apex]`
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[local_weather<br/>Topic] --> B[Call check_weather<br/>backing: Apex]
+```
+
+### Decision/Gating Nodes
+
+Use curly braces `{}` for conditions. Common formats:
+
+- Variable availability gates: `{Check: variable_name != empty?}`
+- Conditional instructions: `{variable_name == value?}`
+- Topic transition logic: `{user_intent matches?}`
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[topic<br/>Topic] --> B{Check: guest_interests<br/>!= empty?}
+    B -->|Yes| C[Call collect_events<br/>backing: Prompt Template]
+    B -->|No| D[Ask for clarification]
+```
+
+### Variable State Change Nodes
+
+Format: `[Set variable_name = value]`
+
+Shows state modifications that affect downstream behavior.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[Call action] --> B[Set reservation_required<br/>= true]
+```
+
+### Utility Call Nodes
+
+Format: `[Call @utils.name]`
+
+For escalation and system utilities.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[escalation<br/>Topic] --> B[Call @utils.escalate]
+```
+
+---
+
+## Topic Map Patterns
+
+### Basic Topic with Single Action
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[start_agent<br/>topic_selector]
+    A -->|route to topic| B[simple_topic<br/>Topic]
+    B --> C[Call do_action<br/>backing: Apex]
+    C --> D[Continue]
+```
+
+### Topic with Gating Condition
+
+Available_when expressions prevent action execution until conditions are met.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[topic_with_gate<br/>Topic]
+    A --> B{Check: required_var<br/>!= empty?}
+    B -->|No| C[Instruction: collect info first]
+    B -->|Yes| D[Call action<br/>backing: Prompt Template]
+    C --> E[Wait for input]
+    E --> A
+```
+
+### Topic with Conditional Instructions
+
+Variable values control which instructions apply to a topic.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[Call process_request<br/>backing: Flow]
+    A --> B[Set status_flag = complete]
+    B --> C{Check: status_flag<br/>== complete?}
+    C -->|Yes| D[Apply conditional<br/>instructions]
+    D --> E[Continue]
+```
+
+### Topic Transitions
+
+When logic determines a new topic should be active.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[current_topic<br/>Topic]
+    A --> B{Transition<br/>condition?}
+    B -->|Yes| C[Transition to<br/>next_topic]
+    C --> D[next_topic<br/>Topic]
+    B -->|No| E[Continue in<br/>current_topic]
+```
+
+### Off-Topic and Escalation Routing
+
+How the agent handles out-of-scope requests.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[start_agent<br/>topic_selector]
+    A -->|out of scope| B[off_topic<br/>Topic]
+    A -->|needs help| C[escalation<br/>Topic]
+    B --> D[Instruction: redirect user]
+    C --> E[Call @utils.escalate]
+```
+
+---
+
+## Complete Example: Local_Info_Agent
+
+This example demonstrates a complete Topic Map for a guest information agent with multiple topics, gating conditions, variable state, and escalation handling.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[start_agent<br/>topic_selector]
+
+    A -->|weather query| B[local_weather<br/>Topic]
+    A -->|events query| C[local_events<br/>Topic]
+    A -->|hours query| D[resort_hours<br/>Topic]
+    A -->|unclear intent| E[ambiguous_question<br/>Topic]
+    A -->|out of scope| F[off_topic<br/>Topic]
+    A -->|needs escalation| G[escalation<br/>Topic]
+
+    B --> B1[Call check_weather<br/>backing: Apex]
+    B1 --> B2[Continue]
+
+    C --> C1{Check: guest_interests<br/>!= empty?}
+    C1 -->|No| C2[Instruction: collect guest interests]
+    C1 -->|Yes| C3[Call check_events<br/>backing: Prompt Template]
+    C2 --> C4[Pause for input]
+    C4 --> C
+    C3 --> C5[Continue]
+
+    D --> D1[Call get_resort_hours<br/>backing: Flow]
+    D1 --> D2[Set reservation_required<br/>= true]
+    D2 --> D3{Check: reservation_required<br/>== true?}
+    D3 -->|Yes| D4[Apply booking instructions]
+    D3 -->|No| D5[Apply standard instructions]
+    D4 --> D6[Continue]
+    D5 --> D6
+
+    E --> E1[Instruction: ask for clarification]
+    E1 --> E2[Await user input]
+    E2 --> A
+
+    F --> F1[Instruction: explain available topics]
+    F1 --> F2[Continue]
+
+    G --> G1[Call @utils.escalate]
+    G1 --> G2[Continue]
+```
+
+### Topic Descriptions
+
+**local_weather**: Provides weather information via Apex-backed action. No preconditions.
+
+**local_events**: Requires guest_interests variable to be populated (gating: `available_when guest_interests != ""`). Calls Prompt Template-backed action only when gate is satisfied.
+
+**resort_hours**: Calls Flow-backed action that sets reservation_required variable. Conditional instructions applied based on variable state: booking-specific guidance when true, standard guidance when false.
+
+**ambiguous_question**: No actions. Requests clarification and routes back to start_agent.
+
+**off_topic**: No actions. Explains available topics and continues conversation.
+
+**escalation**: Calls @utils.escalate utility to route to human agent.
+
+**start_agent topic_selector**: Routes incoming user input to appropriate topics based on intent.
+
+---
+
+## Validation Checklist
+
+Before finalizing a Topic Map diagram:
+
+- [ ] Uses `graph TD` syntax
+- [ ] Starts with `%%{init: {'theme':'neutral'}}%%`
+- [ ] start_agent topic_selector is node A at top
+- [ ] Nodes use sequential capital letter IDs
+- [ ] All topics labeled with `[topic_name<br/>Topic]` format
+- [ ] Action calls include backing type (Apex, Prompt Template, Flow)
+- [ ] Gating conditions shown as decision nodes with `{Check: ...?}` format
+- [ ] Variable state changes explicitly labeled with `[Set variable = value]`
+- [ ] Escalation uses `[Call @utils.escalate]` format
+- [ ] All transition branches are labeled
+- [ ] Diagram fits in 20-30 nodes
+- [ ] Topic routing from start_agent is clear
+- [ ] Off-topic and escalation paths are visible
+- [ ] Conditional instruction logic is shown
+
+---
+
+## Anti-patterns
+
+### Don't
+
+- Use `graph LR` or other orientations instead of `graph TD`
+- Place start_agent anywhere except top (node A)
+- Label actions without backing type information
+- Use ambiguous decision node labels (avoid `{Process?}`)
+- Hide gating conditions in node descriptions instead of showing as decisions
+- Omit variable state changes that affect downstream behavior
+- Create topic routing without labels on the decision logic
+- Mix topic nodes with action nodes at same level without clear containment
+- Use custom color styling (breaks in dark mode)
+- Leave off-topic and escalation paths out of diagram
+
+### Do
+
+- Keep start_agent topic_selector at the top
+- Show all topics reachable from start_agent
+- Include backing type for every action call
+- Make gating conditions explicit as decision nodes
+- Show variable updates as separate nodes when they affect logic flow
+- Label all transition branches
+- Include off-topic and escalation topics
+- Show conditional instructions with decision nodes
+- Use `%%{init: {'theme':'neutral'}}%%` for light/dark mode compatibility
+- Focus diagram on topic structure, not detailed action logic