@salesforce/afv-skills 1.6.8 → 1.7.0

package/skills/{agentforce-development → developing-agentforce}/references/agent-user-setup.md

@@ -18,7 +18,7 @@ PID_DigitalAgent (typically included with Agentforce licenses)
 | **`default_agent_user` in config** | Required | Omit entirely |
 | **Respects Sharing Rules** | No (consistent permissions) | Yes (user's data access) |
 
-**How to check agent type**: Look at the `agent_type` field in the `config:` block of your `.agent` file, or query: `sf data query --query "SELECT DeveloperName, Type FROM BotDefinition WHERE DeveloperName = 'AgentName'" -o TARGET_ORG --json`
+**How to check agent type**: Look at the `agent_type` field in the `config:` block of your `.agent` file, or query: `sf data query --json --query "SELECT DeveloperName, Type FROM BotDefinition WHERE DeveloperName = 'AgentName'" -o TARGET_ORG`
 
 ---
 
@@ -28,18 +28,19 @@ For CLI-first workflow (tested: ~8 minutes total):
 
 ```bash
 # Step 1: Query existing Einstein Agent Users (30 seconds)
-sf data query \
+sf data query --json \
   --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 2: Create Einstein Agent User (2 minutes)
-# Get Profile ID
-PROFILE_ID=$(sf data query \
+# Get Profile ID (read result.records[0].Id from JSON response)
+sf data query --json \
   --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" \
-  -o TARGET_ORG --json | jq -r '.result.records[0].Id')
+  -o TARGET_ORG
 
 # For Production/Sandbox (non-scratch org):
-sf data create record --sobject User --values \
+# Use the ProfileId from the query above
+sf data create record --json --sobject User --values \
   "Username=<agent_name>_user@<orgId>.ext \
    LastName=<AgentName> \
    Email=admin@example.com \
@@ -47,55 +48,55 @@ sf data create record --sobject User --values \
    TimeZoneSidKey=America/Los_Angeles \
    LocaleSidKey=en_US \
    EmailEncodingKey=UTF-8 \
-   ProfileId=${PROFILE_ID} \
+   ProfileId=<PROFILE_ID> \
    LanguageLocaleKey=en_US" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # For Scratch Orgs (use user definition file):
 # sf org create user --definition-file config/einstein-agent-user.json -o TARGET_ORG
 
 # Step 3: Assign System Permission Set (1 minute)
-sf org assign permset \
+sf org assign permset --json \
   --name AgentforceServiceAgentUser \
   --on-behalf-of <agent_name>_user@<orgId>.ext \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 4: Deploy Custom Permission Set (3 minutes)
 # (Create the .permissionset-meta.xml file first - see Section 3.2 template)
-sf project deploy start \
+sf project deploy start --json \
   --metadata PermissionSet:<AgentName>_Access \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Assign custom PS
-sf org assign permset \
+sf org assign permset --json \
   --name <AgentName>_Access \
   --on-behalf-of <agent_name>_user@<orgId>.ext \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 5: Verify All Permissions (1 minute)
-sf data query \
+sf data query --json \
   --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '<agent_name>_user@<orgId>.ext' ORDER BY PermissionSet.Name" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Expected: AgentforceServiceAgentUser + <AgentName>_Access
 
 # Step 6: Deploy Agent Bundle (unpublished metadata)
-sf project deploy start \
+sf project deploy start --json \
   --source-dir force-app/main/default/aiAuthoringBundles/<AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 7: Test BEFORE Publishing (recommended)
-sf agent preview start \
+sf agent preview start --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 # Test all topics and actions to verify permissions
 
 # Step 8: Publish & Activate (only after testing passes)
-sf agent publish authoring-bundle \
+sf agent publish authoring-bundle --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
-sf agent activate \
+sf agent activate --json \
   --api-name <AgentName> \
   -o TARGET_ORG
 ```
@@ -118,19 +119,20 @@ Service agents need a dedicated service account with consistent permissions.
 
 **Get Org ID first** (needed for username format):
 ```bash
-sf org display -o TARGET_ORG --json | jq -r '.result.id'
+sf org display --json -o TARGET_ORG
+# Read result.id from the JSON response
 ```
 
 **Query existing Einstein Agent Users** (skip creation if one exists):
 ```bash
-sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" -o TARGET_ORG
 ```
 
 **Create the user** (if none exists):
 
 1. Get the Einstein Agent User profile ID:
    ```bash
-   sf data query --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" -o TARGET_ORG --json
+   sf data query --json --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" -o TARGET_ORG
    ```
 
 2. Create a user definition file (`config/einstein-agent-user.json`):
@@ -153,7 +155,7 @@ sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Nam
 
    **Option A: Scratch Org (Definition File)**
    ```bash
-   sf org create user \
+   sf org create user --json \
      --definition-file config/einstein-agent-user.json \
      -o TARGET_ORG
    ```
@@ -161,21 +163,22 @@ sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Nam
    **Option B: Production/Sandbox (Direct Record Creation)**
    ```bash
    # Get Profile ID first
-   PROFILE_ID=$(sf data query \
+   # Get Profile ID (read result.records[0].Id from JSON response)
+   sf data query --json \
      --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" \
-     -o TARGET_ORG --json | jq -r '.result.records[0].Id')
+     -o TARGET_ORG
 
-   # Create user directly
-   sf data create record --sobject User --values \
-     "Username='{agent_name}_agent@{orgId}.ext' LastName='{AgentName} Agent' Email='placeholder@example.com' Alias='agntuser' ProfileId='${PROFILE_ID}' TimeZoneSidKey='America/Los_Angeles' LocaleSidKey='en_US' EmailEncodingKey='UTF-8' LanguageLocaleKey='en_US'" \
-     -o TARGET_ORG --json
+   # Create user directly (use ProfileId from query above)
+   sf data create record --json --sobject User --values \
+     "Username='{agent_name}_agent@{orgId}.ext' LastName='{AgentName} Agent' Email='placeholder@example.com' Alias='agntuser' ProfileId='<PROFILE_ID>' TimeZoneSidKey='America/Los_Angeles' LocaleSidKey='en_US' EmailEncodingKey='UTF-8' LanguageLocaleKey='en_US'" \
+     -o TARGET_ORG
    ```
 
    **Note**: `sf org create user` only works in scratch orgs. For production/sandbox, use `sf data create record`. Attempting `sf org create user` in a non-scratch org fails with an authorization error.
 
 4. Verify creation:
    ```bash
-   sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+   sf data query --json --query "SELECT Id, Username, IsActive FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
    ```
 
 **Username format**: `{agent_name}_agent@{orgId}.ext` (production) or `{agent_name}.{suffix}@{orgfarm}.salesforce.com` (dev/scratch). Always query the target org to confirm the exact format.
@@ -192,12 +195,12 @@ Via Setup UI:
 
 Via CLI:
 ```bash
-sf org assign permset --name AgentforceServiceAgentUser --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG --json
+sf org assign permset --json --name AgentforceServiceAgentUser --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG
 ```
 
 Verify assignment:
 ```bash
-sf data query --query "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG
 ```
 
 ---
@@ -230,7 +233,7 @@ Key rule: Include EVERY Apex class referenced via `apex://` in your agent script
 
 Deploy the permission set:
 ```bash
-sf project deploy start --source-dir force-app/main/default/permissionsets/{AgentName}_Access.permissionset-meta.xml -o TARGET_ORG --json
+sf project deploy start --json --source-dir force-app/main/default/permissionsets/{AgentName}_Access.permissionset-meta.xml -o TARGET_ORG
 ```
 
 ---
@@ -239,12 +242,12 @@ sf project deploy start --source-dir force-app/main/default/permissionsets/{Agen
 
 Via CLI:
 ```bash
-sf org assign permset --name {AgentName}_Access --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG --json
+sf org assign permset --json --name {AgentName}_Access --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG
 ```
 
 Verify both permission sets are assigned:
 ```bash
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 ```
 
 Expected output includes both:
@@ -273,9 +276,9 @@ config:
 #### 6.1: Deploy Agent Bundle (Unpublished)
 
 ```bash
-sf project deploy start \
+sf project deploy start --json \
   --source-dir force-app/main/default/aiAuthoringBundles/<AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 This deploys the agent as **unpublished metadata** — you can edit freely without version management.
@@ -283,9 +286,9 @@ This deploys the agent as **unpublished metadata** — you can edit freely witho
 #### 6.2: Test with Preview (Before Publishing)
 
 ```bash
-sf agent preview start \
+sf agent preview start --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 What to test:
@@ -312,9 +315,9 @@ See [preview-test-loop.md](preview-test-loop.md) for the complete smoke test wor
 Only publish after all tests pass.
 
 ```bash
-sf agent publish authoring-bundle \
+sf agent publish authoring-bundle --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 **Publishing does NOT activate.** The new BotVersion is created as `Inactive`. You must explicitly activate.
@@ -322,19 +325,19 @@ sf agent publish authoring-bundle \
 #### 6.4: Activate Agent
 
 ```bash
-sf agent activate \
+sf agent activate --json \
   --api-name <AgentName> \
   -o TARGET_ORG
 ```
 
-`sf agent activate` does NOT support `--json`. It prints a plain-text confirmation.
+Note: `sf agent activate` may not support `--json` in all CLI versions. It prints a plain-text confirmation.
 
 #### 6.5: Verify Activation
 
 ```bash
-sf data query \
+sf data query --json \
   --query "SELECT Id, DeveloperName, Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<AgentName>' ORDER BY CreatedDate DESC LIMIT 1" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 Expected: `Status = 'Active'`
@@ -366,7 +369,7 @@ Same XML template as Step 3 above. Include `<classAccesses>` for all Apex classe
 Assign the custom PS to employees (not to a service account):
 
 ```bash
-sf org assign permset --name {AgentName}_Access --on-behalf-of "employee@company.com" -o TARGET_ORG --json
+sf org assign permset --json --name {AgentName}_Access --on-behalf-of "employee@company.com" -o TARGET_ORG
 ```
 
 Or use Permission Set Groups for role-based access.
@@ -384,7 +387,7 @@ config:
 ### Step 4: Publish
 
 ```bash
-sf agent publish authoring-bundle --api-name Employee_Agent -o TARGET_ORG --json
+sf agent publish authoring-bundle --json --api-name Employee_Agent -o TARGET_ORG
 ```
 
 ---
@@ -409,22 +412,22 @@ Run this combined query to verify all setup steps for a Service Agent:
 
 ```bash
 # 1. Einstein Agent User exists and is active
-sf data query --query "SELECT Id, Username, IsActive, Profile.Name FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, Username, IsActive, Profile.Name FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 
 # 2. System PS assigned
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG
 
 # 3. Custom PS assigned
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = '{AgentName}_Access'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = '{AgentName}_Access'" -o TARGET_ORG
 
 # 4. All permission sets for user (combined view)
-sf data query --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 
 # 5. Agent config has default_agent_user
 # Check your .agent file's config: block
 
 # 6. Agent publishes successfully
-sf agent publish authoring-bundle --api-name AgentName -o TARGET_ORG --json
+sf agent publish authoring-bundle --json --api-name AgentName -o TARGET_ORG
 ```
 
 Checklist:

package/skills/{agentforce-development → developing-agentforce}/references/agent-validation-and-debugging.md

@@ -20,7 +20,7 @@ The `sf agent validate` command checks Agent Script files for syntax errors, str
 After modifying any `.agent` file, always run this command:
 
 ```bash
-sf agent validate authoring-bundle --api-name <AGENT_NAME> --json
+sf agent validate authoring-bundle --json --api-name <AGENT_NAME>
 ```
 
 Replace `<AGENT_NAME>` with the directory name under `aiAuthoringBundles/` (without the `.agent` extension). Always include `--json` so the output is machine-readable.
@@ -28,7 +28,7 @@ Replace `<AGENT_NAME>` with the directory name under `aiAuthoringBundles/` (with
 Example:
 
 ```bash
-sf agent validate authoring-bundle --api-name Local_Info_Agent --json
+sf agent validate authoring-bundle --json --api-name Local_Info_Agent
 ```
 
 ### Interpreting Output
@@ -183,21 +183,21 @@ ALWAYS use `--json` when calling from a script or AI assistant (not interactive
 #### Step 1: Start a Session
 
 ```bash
-sf agent preview start --authoring-bundle <BUNDLE_NAME> --json
+sf agent preview start --json --authoring-bundle <BUNDLE_NAME> --use-live-actions
 ```
 
-This command returns a session ID. Capture it immediately — you need it for every subsequent command.
+This command returns a session ID. Capture it immediately — you need it for every subsequent command. Use `--use-live-actions` to execute real backing logic (recommended). Omit it only when backing logic doesn't exist yet and you want simulated preview.
 
 Example:
 
 ```bash
-sf agent preview start --authoring-bundle Local_Info_Agent --json
+sf agent preview start --json --authoring-bundle Local_Info_Agent --use-live-actions
 ```
 
 #### Step 2: Send Utterances
 
 ```bash
-sf agent preview send --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> -u "<MESSAGE>" --json
+sf agent preview send --json --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> -u "<MESSAGE>"
 ```
 
 Include the same `--authoring-bundle` name and the session ID from Step 1. You can send multiple utterances in the same session — do not end and restart between turns.
@@ -205,13 +205,13 @@ Include the same `--authoring-bundle` name and the session ID from Step 1. You c
 Example:
 
 ```bash
-sf agent preview send --authoring-bundle Local_Info_Agent --session-id abc123def456 -u "What's the weather?" --json
+sf agent preview send --json --authoring-bundle Local_Info_Agent --session-id abc123def456 -u "What's the weather?"
 ```
 
 #### Step 3: End a Session (Optional)
 
 ```bash
-sf agent preview end --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> --json
+sf agent preview end --json --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID>
 ```
 
 This command returns the path to session trace files. Call it when the conversation is complete. Do not end prematurely — if the user may ask follow-up questions, keep the session open.
@@ -229,7 +229,7 @@ Simulated preview mode speeds up inner-loop development but cannot validate real
 **Live Preview Mode.** Real backing code executes and returns real outputs. Pass `--use-live-actions`:
 
 ```bash
-sf agent preview start --authoring-bundle <BUNDLE_NAME> --use-live-actions --json
+sf agent preview start --json --authoring-bundle <BUNDLE_NAME> --use-live-actions
 ```
 
 Use live preview mode when:
@@ -240,6 +240,8 @@ Live preview mode is required for reliable grounding testing. The grounding chec
 
 CRITICAL: `--use-live-actions` is ONLY valid with `--authoring-bundle`. Published agents (`--api-name`) always execute real actions — do NOT pass `--use-live-actions` with `--api-name`.
 
+CRITICAL: `--use-live-actions` is a flag on `preview start` ONLY. Do NOT pass it to `preview send` or `preview end` — those commands do not accept it and will error.
+
 ### Agent Identification
 
 Use exactly one of these mutually exclusive flags:
@@ -264,7 +266,7 @@ The CLI automatically uses the project's default target org. Always omit `--targ
 sf agent preview --authoring-bundle My_Bundle
 
 # CORRECT — programmatic API
-sf agent preview start --authoring-bundle My_Bundle --json
+sf agent preview start --json --authoring-bundle My_Bundle
 ```
 
 The bare `sf agent preview` command is an interactive REPL for humans. Automation cannot provide terminal input (ESC), so it hangs. Use `start`/`send`/`end` with `--json`.
@@ -273,10 +275,10 @@ The bare `sf agent preview` command is an interactive REPL for humans. Automatio
 
 ```bash
 # WRONG — mutually exclusive flags
-sf agent preview start --authoring-bundle My_Bundle --api-name My_Agent --json
+sf agent preview start --json --authoring-bundle My_Bundle --api-name My_Agent
 
 # CORRECT — choose one
-sf agent preview start --authoring-bundle My_Bundle --json
+sf agent preview start --json --authoring-bundle My_Bundle
 ```
 
 These flags are mutually exclusive. Use the one matching your agent type.
@@ -299,11 +301,11 @@ Use `agent preview` commands with `--api-name` to preview published agents.
 
 ```bash
 # WRONG — no session exists
-sf agent preview send --authoring-bundle My_Bundle -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle -u "Hello"
 
 # CORRECT — start first, capture session ID
-sf agent preview start --authoring-bundle My_Bundle --json
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview start --json --authoring-bundle My_Bundle
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 Each session has a unique ID. You must start before sending.
@@ -312,10 +314,10 @@ Each session has a unique ID. You must start before sending.
 
 ```bash
 # WRONG — missing --authoring-bundle
-sf agent preview send --session-id <ID> -u "Hello" --json
+sf agent preview send --json --session-id <ID> -u "Hello"
 
 # CORRECT
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 Every command after `start` must include the same `--authoring-bundle` or `--api-name` flag.
@@ -324,10 +326,10 @@ Every command after `start` must include the same `--authoring-bundle` or `--api
 
 ```bash
 # WRONG — concurrent sessions collide
-sf agent preview send --authoring-bundle My_Bundle -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle -u "Hello"
 
 # CORRECT — always include session ID
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 If multiple agents have concurrent sessions against the same agent, omitting the session ID causes them to interfere. Always pass the session ID from `start`.
@@ -699,7 +701,7 @@ Use this systematic 8-step approach when diagnosing any agent behavior issue.
 
 6. **Fix** — Update Agent Script instructions, variable logic, or action definitions based on what you found.
 
-7. **Validate** — Run `sf agent validate authoring-bundle --api-name <AGENT_NAME> --json` to ensure the fix doesn't introduce syntax errors.
+7. **Validate** — Run `sf agent validate authoring-bundle --json --api-name <AGENT_NAME>` to ensure the fix doesn't introduce syntax errors.
 
 8. **Re-Test** — Run a new preview session with the same input and compare traces. Verify the fix resolved the issue.
 

package/skills/developing-agentforce/references/architecture-patterns.md

@@ -0,0 +1,158 @@
+# Architecture Patterns
+
+> Extracted from SKILL.md Section 8. This file is loaded on demand when architecture pattern guidance is needed.
+
+> All architecture patterns below work for both `AgentforceServiceAgent` and `AgentforceEmployeeAgent`. The only difference is that employee agents cannot use `@utils.escalate` or `connection messaging:` — replace escalation with a `@utils.transition` to a help topic or an action that creates a case/ticket.
+
+## When to Use Each Pattern
+
+| Pattern | Use When |
+|---------|----------|
+| Hub-and-Spoke | Agent has 2+ distinct topics with different intents (most common) |
+| Verification Gate | Sensitive data, payments, or PII require identity verification first |
+| Post-Action Loop | Actions produce state that drives follow-up logic (e.g., risk scoring) |
+| Single Topic | Agent serves one focused purpose with no routing needed |
+
+## Hub-and-Spoke (Most Common)
+
+A central `topic_selector` routes to specialized spoke topics. Each spoke has a "back to hub" transition. Use when users may have multiple distinct intents.
+
+```
+start_agent topic_selector:
+	description: "Route user requests to the appropriate topic"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions directly.
+			Always use a transition action to route immediately.
+		actions:
+			to_orders: @utils.transition to @topic.order_support
+				description: "Order questions"
+			to_returns: @utils.transition to @topic.return_support
+				description: "Return or refund requests"
+			to_general: @utils.transition to @topic.general_support
+				description: "General questions"
+
+topic order_support:
+	description: "Handle order inquiries"
+	reasoning:
+		instructions: ->
+			| Help the customer with their order.
+		actions:
+			lookup: @actions.get_order
+				description: "Look up order"
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+```
+
+> **Routing lives in `start_agent`** -- put all transition actions directly in `start_agent topic_selector:`. Do NOT create a separate routing-only topic (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. Topics that need "go back" should transition to `@topic.topic_selector`.
+
+## Verification Gate
+
+Users must pass through identity verification before accessing protected topics. Use when handling sensitive data, payments, or PII.
+
+```
+start_agent topic_selector:
+	description: "Route through identity verification"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions directly.
+			Route all users to identity verification first.
+		actions:
+			verify: @utils.transition to @topic.identity_verification
+				description: "Begin verification"
+
+topic identity_verification:
+	description: "Verify customer identity"
+	reasoning:
+		instructions: ->
+			if @variables.failed_attempts >= 3:
+				| Too many failed attempts. Transferring to human agent.
+				transition to @topic.escalation
+
+			if @variables.is_verified == True:
+				| Identity verified! How can I help?
+
+			if @variables.is_verified == False:
+				| Please verify your identity.
+
+		actions:
+			verify_email: @actions.verify_identity
+				description: "Verify customer email"
+				set @variables.is_verified = @outputs.verified
+
+			to_account: @utils.transition to @topic.account_mgmt
+				description: "Account management"
+				available when @variables.is_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human"
+```
+
+## Post-Action Loop
+
+The topic re-resolves after an action completes. Place post-action checks at the TOP of `instructions: ->` so they trigger on the loop:
+
+```
+reasoning:
+	instructions: ->
+		# POST-ACTION CHECK (at TOP - triggers on re-resolution)
+		if @variables.refund_status == "Approved":
+			run @actions.create_crm_case
+				with customer_id = @variables.customer_id
+			transition to @topic.confirmation
+
+		# PRE-LLM: Load data
+		run @actions.load_risk_score
+			with customer_id = @variables.customer_id
+			set @variables.risk_score = @outputs.score
+
+		# DYNAMIC INSTRUCTIONS
+		| Risk score: {!@variables.risk_score}
+		if @variables.risk_score >= 80:
+			| HIGH RISK - Offer retention package.
+		else:
+			| STANDARD - Follow normal process.
+```
+
+## Migrating to Hub-and-Spoke
+
+When refactoring a flat agent (all logic in one topic) into hub-and-spoke:
+
+1. **Identify distinct intents** — each becomes a spoke topic
+2. **Move instructions and actions** from the monolithic topic into spoke topics. Each spoke needs BOTH its Level 1 action definitions (under `topic > actions`) AND Level 2 action invocations (under `topic > reasoning > actions`).
+3. **Create `start_agent topic_selector:`** with transition actions pointing to each spoke
+4. **Add "back to hub" transitions** in each spoke: `@utils.transition to @topic.topic_selector`
+5. **Re-preview immediately** — verify topic routing works before making further changes
+
+**Common migration mistakes:**
+- Creating a separate `main_menu` topic instead of using `start_agent topic_selector:` as the hub — adds an unnecessary LLM hop
+- Leaving action definitions in `start_agent` instead of moving them to spoke topics — all actions visible in all topics, confusing the planner
+- Forgetting to add "back to hub" transitions — users get stuck in a spoke topic
+- If trace shows `topic: "DefaultTopic"`, check that topic descriptions contain keywords matching test utterances
+
+## Multi-Intent Handling
+
+When a user sends multiple intents in one message, the start_agent router should handle the first intent and queue the second:
+
+```
+instructions: |
+	You are a router only. Do NOT answer questions directly.
+	If the user asks about multiple topics in one message, route to the first
+	topic. After that task is complete, remind the user about the other request.
+```
+
+## Handling Incomplete Action Inputs
+
+- Use `with param = ...` (slot-fill) for inputs the LLM should extract from conversation
+- Add instructions that tell the LLM to invoke the action with whatever data is available
+- Anti-pattern: Making the LLM ask for ALL inputs before invoking
+
+## Controlling Opportunistic Action Chains
+
+In long action chains (A->B->C->D), the LLM may invoke downstream actions as soon as prerequisites are met. To control this:
+
+- Add explicit gating in instructions: "Only invoke generate_resolution if the user explicitly asks"
+- Use `available when` guards on downstream actions
+- Distinguish between "analyze only" and "full resolution" workflows in instructions
+
+Anti-pattern: Leaving action chains ungated so the LLM runs the entire pipeline for every query.