@salesforce/afv-skills 1.6.9 → 1.7.1

package/skills/developing-agentforce/assets/agents/order-service.agent

@@ -0,0 +1,272 @@
+# Order Service Agent
+# ========================
+#
+# A complex real-world agent for e-commerce customer service featuring:
+# - Verification gate before order access
+# - Multiple specialized topics (order status, tracking, returns)
+# - Two-level action system with Flow targets
+# - after_reasoning for post-action routing
+# - available when guards for conditional action visibility
+
+system:
+	instructions: |
+		You are an AI Customer Service Assistant helping customers with their orders.
+		Be helpful, empathetic, and efficient in resolving order-related issues.
+		Always verify customer identity before sharing order details.
+		Do not fabricate data — always use action results.
+	messages:
+		welcome: "Hello! I'm here to help you with your orders. How can I assist you today?"
+		error: "I apologize for the inconvenience. Let me try a different approach."
+
+config:
+	developer_name: "OrderServiceAgent"
+	agent_label: "Order Service Assistant"
+	description: "Helps customers check order status, process returns, and track shipments"
+	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_email: mutable string = ""
+		description: "Customer email for verification"
+	customer_verified: mutable boolean = False
+		description: "Whether customer identity has been verified"
+	order_number: mutable string = ""
+		description: "Current order number"
+	order_status: mutable string = ""
+		description: "Current order status"
+	tracking_number: mutable string = ""
+		description: "Shipment tracking number"
+	return_reason: mutable string = ""
+		description: "Reason for return"
+	return_initiated: mutable boolean = False
+		description: "Whether a return has been initiated"
+	return_label_url: mutable string = ""
+		description: "URL for return shipping label"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Route customers through verification then to the right topic"
+	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:
+			- Order questions -> use to_orders
+			- Returns -> use to_returns
+			- Tracking -> use to_tracking
+		actions:
+			to_verify: @utils.transition to @topic.verification
+				description: "Begin identity verification"
+			to_orders: @utils.transition to @topic.order_status
+				description: "Check order status"
+				available when @variables.customer_verified == True
+			to_returns: @utils.transition to @topic.returns
+				description: "Process a return"
+				available when @variables.customer_verified == True
+			to_tracking: @utils.transition to @topic.shipment_tracking
+				description: "Track a shipment"
+				available when @variables.customer_verified == True
+
+topic verification:
+	label: "Identity Verification"
+	description: "Verify customer identity before accessing order information"
+
+	actions:
+		verify_customer:
+			description: "Verify customer identity by email"
+			target: "flow://Verify_Customer_Identity"
+			inputs:
+				email: string
+					description: "Customer email address"
+			outputs:
+				verified: boolean
+					description: "Whether verification succeeded"
+				customer_name: string
+					description: "Verified customer name"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == True:
+				| Welcome back! How can I help you today?
+
+			if @variables.customer_verified == False:
+				| To help you with your order, I need to verify your identity.
+				| What is the email address associated with your account?
+
+		actions:
+			verify: @actions.verify_customer
+				description: "Verify customer identity by email"
+				with email = ...
+				set @variables.customer_verified = @outputs.verified
+				set @variables.customer_email = @outputs.customer_name
+
+			proceed_to_orders: @utils.transition to @topic.order_status
+				description: "Move to order lookup"
+				available when @variables.customer_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human agent"
+
+topic order_status:
+	label: "Order Status"
+	description: "Look up order details and provide status updates"
+
+	actions:
+		lookup_order:
+			description: "Look up order by order number"
+			target: "flow://Lookup_Order"
+			inputs:
+				order_number: string
+					description: "Order number to look up"
+				customer_email: string
+					description: "Customer email for validation"
+			outputs:
+				status: string
+					description: "Order status"
+					is_displayable: True
+				tracking_number: string
+					description: "Shipment tracking number"
+					is_displayable: True
+				estimated_delivery: string
+					description: "Estimated delivery date"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.order_status != "":
+				| Order {!@variables.order_number} status: {!@variables.order_status}
+				| Would you like to track your shipment or initiate a return?
+
+			if @variables.order_status == "":
+				| What is your order number? You can find it in your confirmation email.
+				| Use the find_order action to look up order details.
+
+		actions:
+			find_order: @actions.lookup_order
+				description: "Look up order details"
+				with order_number = ...
+				with customer_email = @variables.customer_email
+				set @variables.order_status = @outputs.status
+				set @variables.tracking_number = @outputs.tracking_number
+
+			to_returns: @utils.transition to @topic.returns
+				description: "Start a return"
+				available when @variables.order_status != ""
+
+			to_tracking: @utils.transition to @topic.shipment_tracking
+				description: "Track shipment"
+				available when @variables.tracking_number != ""
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic shipment_tracking:
+	label: "Shipment Tracking"
+	description: "Track shipment status and estimated delivery"
+
+	actions:
+		get_tracking_details:
+			description: "Get detailed tracking information"
+			target: "flow://Get_Tracking_Details"
+			inputs:
+				tracking_number: string
+					description: "Shipment tracking number"
+			outputs:
+				current_location: string
+					description: "Current package location"
+					is_displayable: True
+				estimated_delivery: string
+					description: "Estimated delivery date"
+					is_displayable: True
+				delivery_status: string
+					description: "Delivery status"
+					is_displayable: True
+
+	reasoning:
+		instructions: |
+			Look up the tracking information for the customer's shipment.
+			Use the track action with the tracking number.
+			Do not fabricate tracking details — always use the action result.
+
+		actions:
+			track: @actions.get_tracking_details
+				description: "Get tracking details"
+				with tracking_number = @variables.tracking_number
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic returns:
+	label: "Returns"
+	description: "Process return requests and generate return labels"
+
+	actions:
+		initiate_return:
+			description: "Initiate a return for an order"
+			target: "flow://Initiate_Return"
+			inputs:
+				order_number: string
+					description: "Order number to return"
+				reason: string
+					description: "Reason for return"
+			outputs:
+				return_label_url: string
+					description: "URL for return shipping label"
+					is_displayable: True
+				return_deadline: string
+					description: "Deadline to ship return"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.return_initiated == True:
+				| Your return has been initiated!
+				| Return label: {!@variables.return_label_url}
+
+			if @variables.return_initiated == False:
+				| I can help you with a return for order {!@variables.order_number}.
+				| What is the reason for your return?
+				| Use the process_return action to start the return.
+
+		actions:
+			process_return: @actions.initiate_return
+				description: "Process the return request"
+				with order_number = @variables.order_number
+				with reason = ...
+				set @variables.return_initiated = True
+				set @variables.return_label_url = @outputs.return_label_url
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+	after_reasoning: ->
+		if @variables.return_initiated == True:
+			transition to @topic.follow_up
+
+topic follow_up:
+	label: "Follow Up"
+	description: "Handle follow-up actions and next steps"
+	reasoning:
+		instructions: |
+			The customer's request has been processed.
+			Ask if there is anything else you can help with.
+		actions:
+			new_order: @utils.transition to @topic.order_status
+				description: "Look up another order"
+			back: @utils.transition to @topic.topic_selector
+				description: "Start over"

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:**