@salesforce/afv-skills 1.21.0 → 1.22.0

package/skills/agentforce-generate/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 subagent or an action that creates a case/ticket.
+
+## When to Use Each Pattern
+
+| Pattern | Use When |
+|---------|----------|
+| Hub-and-Spoke | Agent has 2+ distinct subagents 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 Subagent | Agent serves one focused purpose with no routing needed |
+
+## Hub-and-Spoke (Most Common)
+
+A central `agent_router` routes to specialized spoke subagents. Each spoke has a "back to hub" transition. Use when users may have multiple distinct intents.
+
+```
+start_agent agent_router:
+	description: "Route user requests to the appropriate subagent"
+	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 @subagent.order_support
+				description: "Order questions"
+			to_returns: @utils.transition to @subagent.return_support
+				description: "Return or refund requests"
+			to_general: @utils.transition to @subagent.general_support
+				description: "General questions"
+
+subagent 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 @subagent.agent_router
+				description: "Route to a different subagent"
+```
+
+> **Routing lives in `start_agent`** -- put all transition actions directly in `start_agent agent_router:`. Do NOT create a separate routing-only subagent (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. Subagents that need "go back" should transition to `@subagent.agent_router`.
+
+## Verification Gate
+
+Users must pass through identity verification before accessing protected subagents. Use when handling sensitive data, payments, or PII.
+
+```
+start_agent agent_router:
+	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 @subagent.identity_verification
+				description: "Begin verification"
+
+subagent identity_verification:
+	description: "Verify customer identity"
+	reasoning:
+		instructions: ->
+			if @variables.failed_attempts >= 3:
+				| Too many failed attempts. Transferring to human agent.
+				transition to @subagent.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 @subagent.account_mgmt
+				description: "Account management"
+				available when @variables.is_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human"
+```
+
+## Post-Action Loop
+
+The subagent 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 @subagent.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 subagent) into hub-and-spoke:
+
+1. **Identify distinct intents** — each becomes a spoke subagent
+2. **Move instructions and actions** from the monolithic subagent into spoke subagents. Each spoke needs BOTH its Level 1 action definitions (under `subagent > actions`) AND Level 2 action invocations (under `subagent > reasoning > actions`).
+3. **Create `start_agent agent_router:`** with transition actions pointing to each spoke
+4. **Add "back to hub" transitions** in each spoke: `@utils.transition to @subagent.agent_router`
+5. **Re-preview immediately** — verify subagent routing works before making further changes
+
+**Common migration mistakes:**
+- Creating a separate `main_menu` subagent instead of using `start_agent agent_router:` as the hub — adds an unnecessary LLM hop
+- Leaving action definitions in `start_agent` instead of moving them to spoke subagents — all actions visible in all subagents, confusing the planner
+- Forgetting to add "back to hub" transitions — users get stuck in a spoke subagent
+- If trace shows `topic: "DefaultTopic"`, check that subagent 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 subagents in one message, route to the first
+	subagent. 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.

package/skills/agentforce-generate/references/complex-data-types.md

@@ -0,0 +1,57 @@
+<!-- Parent: adlc-author/SKILL.md -->
+
+# `complex_data_type_name` Mapping Table
+
+> **"#1 source of compile errors"** - Use this table when defining action inputs/outputs in Agentforce Assets.
+
+## Decision Tree: When Do I Need `complex_data_type_name`?
+
+1. **Variable** with `number`? → Use `number` directly, no complex type needed
+2. **Action I/O** with integer value, **Flow target** (`flow://`)? → Use `object` + `complex_data_type_name: "lightning__numberType"`
+3. **Action I/O** with integer value, **Apex target** (`apex://`)? → Use `object` + `complex_data_type_name: "lightning__integerType"`
+4. **Action input/output** with decimal value? → Use `object` + `complex_data_type_name: "lightning__doubleType"`
+5. **Variable** with any other primitive? → Use the type directly (`string`, `boolean`, `date`)
+6. **Action I/O** with non-primitive? → Use `object` + appropriate `complex_data_type_name` from table below
+
+> **Key insight:** Bare `number` works in **variable declarations** but **fails at publish** in action inputs/outputs. This is the #1 cause of publish-fix-republish cycles.
+
+> **CRITICAL: Target type matters!** The valid `complex_data_type_name` for integer values differs by target type:
+> - **Flow targets** (`flow://`): Use `lightning__numberType` (NOT `lightning__integerType`)
+> - **Apex targets** (`apex://`): Use `lightning__integerType` (NOT `lightning__numberType`)
+> Using the wrong one causes a publish validation error.
+
+## Full Mapping Table
+
+| Data Type | `complex_data_type_name` Value | Notes |
+|-----------|-------------------------------|-------|
+| `string` | *(none needed)* | Primitive type — works in both variables and action I/O |
+| `number` (variable only) | *(none needed)* | **Variables only** — do NOT use bare `number` in action I/O |
+| `boolean` | *(none needed)* | Primitive type |
+| `object` (SObject) | `lightning__recordInfoType` | Use for Account, Contact, etc. |
+| `list[string]` | `lightning__textType` | Collection of text values |
+| `list[object]` | `lightning__textType` | Serialized as JSON text |
+| Apex Inner Class | `@apexClassType/NamespacedClass__InnerClass` | Namespace required |
+| Custom LWC Type | `lightning__c__CustomTypeName` | Custom component types |
+| Currency field | `lightning__currencyType` | For monetary values |
+| `datetime` | `lightning__dateTimeStringType` | DateTime values |
+| `integer` | `lightning__integerType` | Integer numbers (action I/O only) |
+| `double` / `number` | `lightning__doubleType` | Decimal/floating-point numbers (action I/O only) |
+| `object` (structured) | `lightning__objectType` | Complex data structures (action I/O only) |
+| `list` (generic) | `lightning__listType` | Arrays/lists (action I/O only) |
+
+> **Naming variance**: Upstream documentation uses `lightning__dateTimeType` while testing confirms `lightning__dateTimeStringType`. Both may be valid depending on API version — use `lightning__dateTimeStringType` as the tested default.
+
+## Agent Script → Lightning Type Mapping
+
+> Use this when troubleshooting type errors between Agent Script action I/O and Apex/Flow targets.
+
+| Agent Script Type | Lightning Type | Apex Type | Notes |
+|-------------------|---------------|-----------|-------|
+| `string` | `lightning__textType` | `String` | No `complex_data_type_name` needed |
+| `number` | `lightning__numberType` | `Decimal` / `Double` | No `complex_data_type_name` needed |
+| `boolean` | `lightning__booleanType` | `Boolean` | No `complex_data_type_name` needed |
+| `datetime` | `lightning__dateTimeStringType` | `DateTime` | **Actions only** — not valid for variables |
+| `date` | `lightning__dateType` | `Date` | Valid for both variables and actions |
+| `currency` | `lightning__currencyType` | `Decimal` | Annotated with currency type |
+
+**Pro Tip**: Don't manually edit `complex_data_type_name` - use the UI dropdown in **Agentforce Assets > Action Definition**, then export/import the action definition.

package/skills/agentforce-generate/references/deploy-reference.md

@@ -0,0 +1,134 @@
+# Deploy -- Bundle Publication Reference
+
+> Extracted from SKILL.md Section 18. This file is loaded on demand when deployment details are needed.
+
+## Overview
+
+Full deployment lifecycle for Agentforce agents: validate, deploy metadata, publish bundle, and activate.
+
+## Usage
+
+```bash
+# Validate + publish
+sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
+
+# Activate after publish
+sf agent activate --json --api-name MyAgent -o <org-alias>
+```
+
+## Deployment Phases
+
+### Phase 0: Safety Gate (Required)
+Read the `.agent` file and run safety review (see `safety-review-reference.md`). If any BLOCK finding exists, STOP deployment. WARN findings must be reported and acknowledged by the user before proceeding.
+
+### Phase 1: Pre-Deployment Validation
+```bash
+sf agent validate authoring-bundle --json --api-name MyAgent -o <org-alias>
+```
+
+### Phase 1b: Target Dependency Check
+Verify all flow/apex targets exist in the org before publishing. If missing, scaffold and deploy them first.
+
+### Phase 2: Deploy Supporting Metadata
+```bash
+sf project deploy start --json --source-dir force-app -o <org-alias>
+```
+
+### Phase 3: Publish Agent Bundle
+```bash
+sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
+```
+4-step process: Validate (~1-2s) -> Publish (~8-10s) -> Retrieve (~5-7s) -> Deploy (~4-6s)
+
+### Phase 4: Activate Agent
+```bash
+sf agent activate --json --api-name MyAgent -o <org-alias>
+```
+Note: `sf agent activate` may not support `--json` in all CLI versions. If it returns plain text, check for "successfully activated" in the output.
+
+Publishing creates an **inactive** version. Without activation, preview fails with "No valid version available".
+
+## Deploy vs Publish
+
+| What changes | `sf project deploy start` | `sf agent publish authoring-bundle` |
+|---|---|---|
+| Bundle metadata | Yes | Yes |
+| `system: instructions:` | Yes (via activate) | Yes |
+| `reasoning: actions:` (transitions + invocations) | **NO** | Yes |
+
+**Always prefer `sf agent publish authoring-bundle`.** If you change `reasoning: actions:`, publish is required.
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Required fields missing: [BundleType]` | Extra fields in bundle-meta.xml | Use minimal: only `<bundleType>AGENT</bundleType>` |
+| `Internal Error, try again later` | Invalid default_agent_user or new agent platform bug | Query Einstein Agent Users; for new agents, create shell in Setup UI first |
+| `Duplicate value found: GenAiPluginDefinition` | `start_agent` and `subagent` share name | Use different names |
+| `Flow not found` | Metadata not deployed | Deploy flows before publishing |
+| `SetupEntityType is not supported for DML` | PermissionSet via Apex DML | Use Metadata API (`sf project deploy start`) |
+
+## Rollback
+
+```bash
+sf agent deactivate --json --api-name MyAgent -o <org>
+sf data query --json --query "SELECT Id, VersionNumber FROM BotVersion WHERE BotDefinition.DeveloperName = 'MyAgent' ORDER BY VersionNumber DESC LIMIT 2" -o <org>
+sf agent activate --json --api-name MyAgent --version-number <previous> -o <org>
+```
+
+## CI/CD Integration
+
+```yaml
+name: Deploy Agentforce Agent
+on:
+  push:
+    branches: [main]
+    paths: ['force-app/**']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install SF CLI
+        run: npm install -g @salesforce/cli
+      - name: Auth
+        run: |
+          echo "${{ secrets.SFDX_AUTH_URL }}" > auth.txt
+          sf org login sfdx-url --sfdx-url-file auth.txt --alias production
+      - name: Validate
+        run: sf agent validate authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
+      - name: Deploy Metadata
+        run: sf project deploy start --json --source-dir force-app -o production
+      - name: Publish
+        run: sf agent publish authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
+      - name: Activate
+        if: github.ref == 'refs/heads/main'
+        run: sf agent activate --json --api-name ${{ vars.AGENT_NAME }} -o production
+```
+
+## Pre-Deployment Checklist
+
+- [ ] All action targets exist in org (run discover first)
+- [ ] Agent Script validated (no syntax errors)
+- [ ] Einstein Agent User configured correctly
+- [ ] Supporting metadata deployed
+- [ ] Previous version backed up
+- [ ] Rollback plan documented
+
+## Post-Deployment Testing
+
+```bash
+sf agent preview start --json --use-live-actions --authoring-bundle MyAgent -o <org>
+# Read sessionId from the JSON response, then:
+sf agent preview send --json --authoring-bundle MyAgent --session-id <SESSION_ID> -u "Hello, I need help" -o <org>
+sf agent preview end --json --authoring-bundle MyAgent --session-id <SESSION_ID> -o <org>
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation/deployment failed |
+| 2 | Critical failure |

package/skills/agentforce-generate/references/discover-reference.md

@@ -0,0 +1,102 @@
+# Discover -- Target Discovery Reference
+
+> Extracted from SKILL.md Section 16. This file is loaded on demand when target discovery details are needed.
+
+## Overview
+
+Validates that Agent Script `.agent` file targets actually exist in a Salesforce org, providing fuzzy suggestions for missing targets.
+
+## Usage
+
+```bash
+# List all active autolaunched flows (candidate action targets)
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName,ProcessType+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o <org-alias>
+
+# List all @InvocableMethod Apex classes
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+Name+FROM+ApexClass+WHERE+Body+LIKE+'%25InvocableMethod%25'" -o <org-alias>
+```
+
+## What it does
+
+### 1. Target Extraction
+- Finds all `.agent` files in the project
+- Parses each file to extract action `target:` values
+- Identifies target types: `flow://`, `apex://`, `retriever://`, `externalService://`, `generatePromptResponse://`
+
+### 2. Org Validation
+
+| Target Type | SOQL Query | Object Checked |
+|-------------|------------|----------------|
+| `flow://FlowName` | `SELECT ApiName FROM FlowDefinitionView WHERE ApiName = 'FlowName' AND IsActive = true` | Active flows only |
+| `apex://ClassName` | `SELECT Name FROM ApexClass WHERE Name = 'ClassName'` | Apex classes |
+| `retriever://RetrieverName` | `SELECT DeveloperName FROM DataKnowledgeSpace WHERE DeveloperName = 'RetrieverName'` | Data Cloud retrievers |
+| `externalService://ServiceName` | `SELECT DeveloperName FROM ExternalServiceRegistration WHERE DeveloperName = 'ServiceName'` | External services |
+| `generatePromptResponse://TemplateName` | `SELECT DeveloperName FROM PromptTemplate WHERE DeveloperName = 'TemplateName' AND Status = 'Active'` | Active prompt templates |
+
+### 3. Fuzzy Matching
+When a target is missing:
+- Queries for similar names using SOQL `LIKE` patterns
+- Calculates Levenshtein distance for close matches
+- Suggests up to 3 alternatives sorted by similarity
+
+### 4. I/O Parameter Validation (--validate-io)
+- **Flows:** Queries `/services/data/v63.0/actions/custom/flow/{FlowApiName}` for actual I/O schema
+- **Apex:** Checks `@InvocableVariable` field names match expected inputs/outputs
+- Results appear as non-blocking warnings
+
+### 5. Classification for Scaffold Pipeline
+
+| Signal in Description | Classification | Scaffold Output |
+|----------------------|---------------|-----------------|
+| "API", "HTTP", "REST", "external", URL | `callout` | Apex with Http + Remote Site + Custom Metadata |
+| SObject names, "query", "record", "SOQL" | `soql` | Apex with SOQL query logic |
+| No special signals | `basic` | Standard placeholder Apex |
+
+## Output Format
+
+```
+Agentforce ADLC Discovery Report
+
+Agent: OrderManagement
+  Subagent: order_inquiry
+    Action: get_order_status
+      Target: flow://Get_Order_Status         Found
+    Action: track_shipment
+      Target: flow://Track_Shipment_Flow      MISSING
+        Suggestions:
+          - Track_Shipping_Flow (distance: 2)
+
+Summary: 2/3 targets found (66.7%)
+```
+
+## Next Steps
+
+- Missing targets: Run scaffold to generate stubs (see `scaffold-reference.md`)
+- All found: Deploy (`sf agent publish authoring-bundle --json --api-name <AgentName> -o <org-alias>`)
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `No .agent files found` | Wrong directory | Check `--agent-file` path |
+| `Invalid org alias` | Org not authenticated | Run `sf org login web --alias <org-alias>` |
+| `SOQL query failed` | Missing permissions | Ensure read access to Flow, ApexClass, etc. |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All targets found |
+| 1 | Some targets missing |
+| 2 | Critical failure |
+
+## Advanced (requires ADLC repo clone)
+
+The `discover.py` script provides automated discovery with fuzzy matching and I/O validation. It is NOT bundled with the skill — requires cloning the ADLC repo.
+
+```bash
+# From ADLC repo root:
+python3 scripts/discover.py -o <org-alias> --agent-file <path-to-agent-file>
+python3 scripts/discover.py -o <org-alias> --agent-dir force-app/main/default/aiAuthoringBundles
+python3 scripts/discover.py -o <org-alias> --agent-file MyAgent.agent --validate-io
+```