@salesforce/afv-skills 1.6.9 → 1.7.0

package/skills/developing-agentforce/assets/agents/verification-gate.agent

@@ -0,0 +1,280 @@
+# Verification Gate Architecture Template
+# ========================================
+#
+# Users must pass identity verification before accessing protected topics.
+#
+# Pattern: Security gate before protected functionality.
+# Use when: Handling sensitive data, payments, PII access.
+#
+# Key features:
+# - Deterministic verification (code-enforced, not LLM suggestions)
+# - available when guards make actions invisible until verified
+# - Post-action checks at TOP of instructions: ->
+# - Automatic escalation after 3 failed attempts
+
+system:
+	instructions: |
+		You are an AI secure customer service agent.
+		Always verify identity before sensitive operations.
+		Do not fabricate data — always use action results.
+	messages:
+		welcome: "Welcome! I'll need to verify your identity before we proceed."
+		error: "I apologize, something went wrong. Let me try again."
+
+config:
+	developer_name: "SecureAgent"
+	agent_label: "Secure Customer Agent"
+	description: "Agent with verification gate for sensitive operations"
+	default_agent_user: "einsteinagent@00dxx000001234.ext"
+
+variables:
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+		visibility: "External"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+		visibility: "External"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+		visibility: "External"
+	customer_verified: mutable boolean = False
+		description: "Has customer passed identity verification"
+	failed_attempts: mutable number = 0
+		description: "Number of failed verification attempts"
+	customer_email: mutable string = ""
+		description: "Customer email for verification"
+	refund_status: mutable string = ""
+		description: "Status of refund operation"
+	refund_amount: mutable number = 0
+		description: "Refund amount to process"
+	churn_risk_score: mutable number = 0
+		description: "Customer churn risk from Data Cloud"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Route through identity verification"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions or provide help directly.
+			Route all users to identity verification first.
+			If already verified, route to the appropriate topic:
+			- Account questions -> use to_account
+			- Refund requests -> use to_refund
+		actions:
+			to_verify: @utils.transition to @topic.identity_verification
+				description: "Begin identity verification"
+			to_account: @utils.transition to @topic.account_management
+				description: "Access account settings"
+				available when @variables.customer_verified == True
+			to_refund: @utils.transition to @topic.refund_processor
+				description: "Process a refund request"
+				available when @variables.customer_verified == True
+
+topic identity_verification:
+	label: "Identity Verification"
+	description: "Verify customer identity before proceeding"
+
+	actions:
+		verify_email:
+			description: "Verify customer email against records"
+			target: "flow://Verify_Customer_Email"
+			inputs:
+				email: string
+					description: "Customer email to verify"
+			outputs:
+				verified: boolean
+					description: "Whether verification succeeded"
+
+	reasoning:
+		instructions: ->
+			if @variables.failed_attempts >= 3:
+				| Too many failed attempts. Transferring to a human agent.
+				transition to @topic.escalation
+
+			if @variables.customer_verified == True:
+				| Identity verified! How can I help you today?
+
+			if @variables.customer_verified == False:
+				| Please verify your identity by confirming your email address.
+
+		actions:
+			check_email: @actions.verify_email
+				description: "Verify customer email"
+				with email = ...
+				set @variables.customer_verified = @outputs.verified
+
+			go_to_account: @utils.transition to @topic.account_management
+				description: "Access account settings"
+				available when @variables.customer_verified == True
+
+			go_to_refund: @utils.transition to @topic.refund_processor
+				description: "Process a refund request"
+				available when @variables.customer_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human agent"
+
+topic account_management:
+	label: "Account Management"
+	description: "Manage customer account settings (requires verification)"
+
+	actions:
+		update_email:
+			description: "Update customer email address"
+			target: "apex://UpdateCustomerEmail"
+			inputs:
+				new_email: string
+					description: "New email address"
+			outputs:
+				success: boolean
+					description: "Whether update succeeded"
+
+		update_preferences:
+			description: "Update communication preferences"
+			target: "apex://UpdatePreferences"
+			inputs:
+				pref_type: string
+					description: "Preference type to update"
+				pref_value: string
+					description: "New preference value"
+			outputs:
+				success: boolean
+					description: "Whether update succeeded"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == False:
+				transition to @topic.identity_verification
+
+			| Welcome to account management.
+			| What would you like to do with your account?
+			| Use the update actions to make changes.
+
+		actions:
+			change_email: @actions.update_email
+				description: "Update email address"
+				with new_email = ...
+				available when @variables.customer_verified == True
+
+			change_prefs: @actions.update_preferences
+				description: "Update communication preferences"
+				with pref_type = ...
+				with pref_value = ...
+				available when @variables.customer_verified == True
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Return to main menu"
+
+topic refund_processor:
+	label: "Refund Processor"
+	description: "Process refund requests (requires verification)"
+
+	actions:
+		check_churn_risk:
+			description: "Check customer churn risk score"
+			target: "apex://CheckChurnRisk"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+			outputs:
+				score: object
+					description: "Churn risk score 0-100"
+					complex_data_type_name: "lightning__numberType"
+
+		process_refund:
+			description: "Process a full cash refund"
+			target: "flow://Process_Refund"
+			inputs:
+				refund_type: string
+					description: "Type of refund (full or partial)"
+			outputs:
+				status: string
+					description: "Refund status"
+
+		issue_credit:
+			description: "Issue store credit"
+			target: "flow://Issue_Store_Credit"
+			inputs:
+				amount: object
+					description: "Credit amount"
+					complex_data_type_name: "lightning__numberType"
+			outputs:
+				status: string
+					description: "Credit status"
+
+		create_crm_case:
+			description: "Create a CRM case for the refund"
+			target: "flow://Create_CRM_Case"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+				refund_amount: object
+					description: "Refund amount"
+					complex_data_type_name: "lightning__numberType"
+			outputs:
+				case_id: string
+					description: "Created case ID"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == False:
+				transition to @topic.identity_verification
+
+			if @variables.refund_status == "Approved":
+				run @actions.create_crm_case
+					with customer_id = @variables.ContactId
+					with refund_amount = @variables.refund_amount
+				transition to @topic.success_confirmation
+
+			run @actions.check_churn_risk
+				with customer_id = @variables.ContactId
+				set @variables.churn_risk_score = @outputs.score
+
+			| Customer risk score: {!@variables.churn_risk_score}
+
+			if @variables.churn_risk_score >= 80:
+				| HIGH RISK - Offer a full cash refund to retain this customer.
+			else:
+				| STANDARD - Offer a $10 store credit as goodwill.
+
+		actions:
+			approve_full_refund: @actions.process_refund
+				description: "Approve full cash refund"
+				available when @variables.churn_risk_score >= 80
+				with refund_type = "full"
+				set @variables.refund_status = @outputs.status
+
+			offer_credit: @actions.issue_credit
+				description: "Offer store credit"
+				available when @variables.churn_risk_score < 80
+				with amount = 10
+				set @variables.refund_status = @outputs.status
+
+topic success_confirmation:
+	label: "Success Confirmation"
+	description: "Confirm successful operation"
+	reasoning:
+		instructions: |
+			Great news! Your request has been processed successfully.
+			Is there anything else I can help you with?
+		actions:
+			new_request: @utils.transition to @topic.topic_selector
+				description: "Start a new request"
+
+topic escalation:
+	label: "Escalation"
+	description: "Escalate to human agent"
+	reasoning:
+		instructions: |
+			I'm transferring you to a human agent who can better assist you.
+			Please hold while I connect you.
+		actions:
+			handoff: @utils.escalate
+				description: "Transfer to human agent"

package/skills/{agentforce-development → developing-agentforce}/assets/bundle-meta.xml

@@ -14,7 +14,7 @@
       └── MyAgent.bundle-meta.xml    <- This file (rename to match agent)
 
   DEPLOYMENT COMMAND:
-  sf agent publish authoring-bundle --api-name MyAgent --target-org TARGET_ORG
+  sf agent publish authoring-bundle --json --api-name MyAgent --target-org TARGET_ORG
 
   DO NOT USE: sf project deploy start (will fail with "Required fields are missing: [BundleType]")
 -->

package/skills/{agentforce-development → developing-agentforce}/references/actions-reference.md

@@ -43,6 +43,24 @@ All actions in Agent Script support these properties:
 | `filter_from_agent` | Boolean | `True` = exclude output from agent context; defaults to `False` |
 | `is_used_by_planner` | Boolean | `True` = LLM can reason about this value for routing decisions; defaults to `False` |
 | `complex_data_type_name` | String | Lightning data type mapping (required for complex types) |
+| `is_displayable` | Boolean | `False` = hide from user display (compile-valid alias for `filter_from_agent: True`) |
+
+> **Note**: `filter_from_agent: True` is the GA standard. `is_displayable: False` is a compile-valid alias with the same effect.
+
+> **Safety**: For service agents (customer-facing), internal business metrics (risk scores, retention tiers, churn probability, internal classification codes) should be `filter_from_agent: True` so the LLM can use them for reasoning but they don't appear in customer-facing responses.
+
+### Zero-Hallucination Intent Classification Pattern
+
+Use `filter_from_agent: True` + `is_used_by_planner: True` to let the LLM route based on action outputs without being able to show them to the user:
+
+```agentscript
+outputs:
+   intent_classification: string
+      filter_from_agent: True     # LLM cannot show this to user
+      is_used_by_planner: True    # LLM can use for routing decisions
+```
+
+This prevents the LLM from fabricating classification results — it must invoke the action to get the value, then can only use it for routing decisions.
 
 ### Example with All Properties
 
@@ -476,6 +494,8 @@ public class WrappedAction {
 
 The `connection` block enables escalation to human agents via Omni-Channel. Always use `connection messaging:` (singular).
 
+> **Service agents only.** The `connection messaging:` block and `@utils.escalate` are only valid for `AgentforceServiceAgent`. Employee agents (`AgentforceEmployeeAgent`) MUST NOT include a `connection` block or `@utils.escalate` actions — including them causes silent failures or "unknown error" at publish time. For employee agents, use `@utils.transition` to a help topic or an action that creates a support case instead.
+
 ### Basic Syntax
 
 ```agentscript

package/skills/{agentforce-development → developing-agentforce}/references/agent-design-and-spec-creation.md

@@ -565,7 +565,7 @@ Second, find the default package directory by reading `sfdx-project.json` at the
 Third, generate an empty Apex class using the following command:
 
 ```bash
-sf template generate apex class --name InvoiceFetcher --output-dir <PACKAGE_DIR>/main/default/classes
+sf template generate apex class --json --name InvoiceFetcher --output-dir <PACKAGE_DIR>/main/default/classes
 ```
 
 This creates both the `.cls` and `.cls-meta.xml` files. Do not create test classes for stubs.

package/skills/{agentforce-development → developing-agentforce}/references/agent-metadata-and-lifecycle.md

@@ -58,7 +58,7 @@ Authoring bundles are stored in `<packageDirectory>/main/default/aiAuthoringBund
 
 Publishing creates the runtime entities that make an agent usable in the org.
 
-**Bot** — Top-level container (one per agent). Links to all published versions.
+**Bot** — Top-level container (one per agent). Links to all published versions. Query `BotDefinition` when the ID of a published agent is required. See [CLI for Agents](salesforce-cli-for-agents.md) for query syntax.
 
 **BotVersion** — One per published version (e.g., `v1`, `v2`, `v3`). Only one version can be active at a time.
 
@@ -519,12 +519,12 @@ Agent testing requires a test spec (YAML), which gets compiled into `AiEvaluatio
 
 **Create a test spec from the skill template:**
 
-Copy the test spec template from the **agentforce-testing** skill to `specs/<Agent_API_Name>-testSpec.yaml` in the user's SFDX project. Update `name`, `description`, `subjectName`, and `testCases` to match the agent being tested.
+Copy the test spec template from the **testing-agentforce** skill to `specs/<Agent_API_Name>-testSpec.yaml` in the user's SFDX project. Update `name`, `description`, `subjectName`, and `testCases` to match the agent being tested.
 
 Do NOT use `sf agent generate test-spec` to create a new test spec. This command requires interactive input and cannot be used programmatically. It can reverse-engineer a test spec from an existing `AiEvaluationDefinition` when supplied with the `--from-definition` flag:
 
 ```bash
-sf agent generate test-spec --from-definition force-app/main/default/aiEvaluationDefinitions/Local_Info_Agent_Test.aiEvaluationDefinition-meta.xml --output-file specs/Local_Info_Agent-testSpec.yaml
+sf agent generate test-spec --json --from-definition force-app/main/default/aiEvaluationDefinitions/Local_Info_Agent_Test.aiEvaluationDefinition-meta.xml --output-file specs/Local_Info_Agent-testSpec.yaml
 ```
 
 **Create the test in the org:**

package/skills/{agentforce-development → developing-agentforce}/references/agent-script-core-language.md

@@ -192,8 +192,8 @@ The expression inside `{! ... }` is evaluated by the runtime during deterministi
 - `@topic.<name>` — reference a topic by name
 - `@variables.<name>` — reference a variable (use in logic)
 - `{!@variables.<name>}` — reference a variable in prompt text (template injection)
-- `@outputs.<name>` — reference an action output (only in post-action context)
-- `@inputs.<name>` — reference an action input (in action definition)
+- `@outputs.<name>` — action output (only in `set`/`if` immediately after the action — unavailable elsewhere)
+- `@inputs.<name>` — action input (only in `with` during invocation — NOT in `set` or post-execution)
 - `@utils.<function>` — reference a utility (escalate, transition to, setVariables)
 
 **Do NOT use `<>` as inequality operator.** Use `!=` instead.
@@ -243,6 +243,26 @@ config:
     - `default_agent_user`
     - MessagingSession linked variables (`EndUserId`, `RoutableId`, `ContactId`, `EndUserLanguage`)
     - Escalation topic with `@utils.escalate`
+    - `connection messaging:` block
+
+  **Common mistake — service-agent constructs on employee agent:**
+
+  ```agentscript
+  # WRONG — employee agent with service-agent constructs
+  config:
+      agent_type: "AgentforceEmployeeAgent"
+      default_agent_user: "agent@org.ext"    # PROHIBITED — causes "Internal Error"
+  variables:
+      EndUserId: linked string               # SERVICE ONLY — no messaging session
+          source: @MessagingSession.MessagingEndUserId
+  connection messaging:                       # SERVICE ONLY — no messaging channel
+      escalation_message: "Transferring..."
+
+  # RIGHT — clean employee agent config
+  config:
+      agent_type: "AgentforceEmployeeAgent"
+      # No default_agent_user, no MessagingSession vars, no connection block
+  ```
 
 **Conditionally required fields:**
 - `default_agent_user` — **required for `AgentforceServiceAgent`, prohibited for `AgentforceEmployeeAgent`**. This is the Salesforce username of the Einstein Agent User that runs agent actions on behalf of the customer. The user must exist in the target org, be active, and have the Einstein Agent license assigned.
@@ -528,6 +548,23 @@ run @actions.process_order
 
 After an action completes, you can check outputs and transition.
 
+**Scope lifecycle — `@inputs` and `@outputs` are ephemeral:**
+- `@inputs`: only in `with` directives during invocation. NOT in `set`/`if` after execution.
+- `@outputs`: only in `set`/`if` immediately after invocation. NOT in instructions or later actions.
+- To reuse an input value post-execution, capture it in `@variables` BEFORE the action call.
+
+```agentscript
+# WRONG — silent failure, @inputs out of scope in set
+run @actions.get_station_status
+    with station_name = ...
+    set @variables.station = @inputs.station_name   # FAILS SILENTLY
+
+# RIGHT — use @outputs (if action echoes value) or capture input beforehand
+run @actions.get_station_status
+    with station_name = ...
+    set @variables.station = @outputs.station_name
+```
+
 **How pipe sections become the LLM prompt**:
 
 All logic is resolved first; only matching `|` pipe lines are included in the prompt:
@@ -852,7 +889,7 @@ reasoning:
 
 Transition discards the current topic's prompt and starts fresh with the target topic.
 
-**`@utils.escalate`** — route to a human agent:
+**`@utils.escalate`** — route to a human agent (**service agents only** — requires a `connection messaging:` block, which is only valid for `AgentforceServiceAgent`; do not use in employee agents):
 
 ```agentscript
 reasoning: