@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/developing-agentforce/assets/agent-spec-template.md

@@ -1,90 +0,0 @@
-# Agent Spec: Agent_API_Name
-
-## Purpose & Scope
-
-Describe the agent's purpose in 1-2 sentences. What does it help users do?
-What domain does it operate in?
-
-## Behavioral Intent
-
-Describe the key behavioral rules that govern the agent:
-- What must the agent know before taking action?
-- What backing logic types are used (Apex, Flow, Prompt Template)?
-- What guardrails apply (off-topic handling, escalation)?
-- What information persists across subagent switches?
-
-## Subagent Map
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-graph TD
-    A[start_agent<br/>agent_router]
-
-    A -->|description of routing condition| B[subagent_name<br/>Subagent]
-    A -->|unclear intent| C[ambiguous_question<br/>Subagent]
-    A -->|out of scope| D[off_topic<br/>Subagent]
-    A -->|needs escalation| E[escalation<br/>Subagent]
-```
-
-Expand the diagram to show actions, gating logic, and variable state changes
-within each subagent. See the Subagent Map Diagrams reference for conventions.
-
-## Variables
-
-- `variable_name` (mutable type = default) — What this variable tracks.
-  Set by: which action or utility. Read by: which topics for gating or
-  conditional instructions.
-
-## Actions & Backing Logic
-
-### action_name (subagent_name subagent)
-
-- **Target:** `apex://ClassName` or `flow://FlowName` or `prompt://PromptTemplateName`
-- **Backing Status:** EXISTS / NEEDS STUB / NEEDS IMPLEMENTATION
-
-#### Inputs
-
-| Name | Type | Required | Source |
-|------|------|----------|--------|
-| property_id | string | Yes | User input |
-| max_results | integer | No | Defaults to 10 |
-
-#### Outputs
-
-| Name | Type | Visible to User? | Source | Notes |
-|------|------|-------------------|--------|-------|
-| property | object | Yes | `Property__c` | Complete property details |
-| related_applications | list[object] | Yes | `Application__c` | Records for this property |
-| active_listing | boolean | Yes | `Listing__c` | Listing status |
-| hasData | boolean | No | Computed | Internal empty-result flag |
-
-> **"Visible to User?"** maps to `filter_from_agent` in the `.agent` file: Yes → `filter_from_agent: False`, No → `filter_from_agent: True`.
-
-#### Stubbing Requirement
-
-If NEEDS STUB:
-
-- Apex class name and inner class wrappers needed
-- `complex_data_type_name` for each `object`/`list[object]` output
-- Key queries or computation logic the stub must implement
-
-Repeat for each action.
-
-## Gating Logic
-
-- `action_name` visibility: `available when @variables.variable_name != ""`
-  — Rationale for why this gate exists.
-
-List all gating conditions with their rationale.
-
-## Architecture Pattern
-
-State the architecture pattern: hub-and-spoke, chain, hybrid, etc.
-Describe the routing strategy and how topics relate to each other.
-
-## Agent Configuration
-
-- **developer_name:** `Agent_API_Name`
-- **agent_label:** `Agent Display Name`
-- **agent_type:** `AgentforceEmployeeAgent` or `AgentforceServiceAgent` — state the reasoning based on prompt signals (e.g., "accessible by employees" → Employee, "customer-facing channel" → Service)
-- **default_agent_user:** Required for `AgentforceServiceAgent`. Forbidden for `AgentforceEmployeeAgent`. If specified, MUST be **user name**. MUST NEVER be **user ID**. User MUST have `Einstein Agent` license.

package/skills/developing-agentforce/assets/agents/README.md

@@ -1,45 +0,0 @@
-# Complete Agent Templates
-
-Templates for building complete, deployable agents.
-
-## Learning Path
-
-| Template | Complexity | Description |
-|----------|------------|-------------|
-| `hello-world.agent` | Beginner | Minimal viable agent - start here |
-| `simple-qa.agent` | Beginner | Single-subagent Q&A agent |
-| `multi-subagent.agent` | Intermediate | Multi-subagent routing agent |
-| `production-faq.agent` | Advanced | Production-ready FAQ with escalation |
-
-## Quick Start
-
-1. Copy a template to your SFDX project:
-   ```bash
-   mkdir -p force-app/main/default/aiAuthoringBundles/My_Agent
-   cp hello-world.agent force-app/main/default/aiAuthoringBundles/My_Agent/My_Agent.agent
-   cp ../metadata/bundle-meta.xml force-app/main/default/aiAuthoringBundles/My_Agent/My_Agent.bundle-meta.xml
-   ```
-
-2. Validate and deploy:
-   ```bash
-   sf agent validate authoring-bundle --json --api-name My_Agent --target-org your-org
-   sf agent publish authoring-bundle --json --api-name My_Agent --target-org your-org
-   ```
-
-## Required Blocks
-
-Every agent must have these blocks **in this order**:
-
-| Block | Purpose |
-|-------|---------|
-| `system:` | Agent personality and default messages |
-| `config:` | Deployment metadata (agent_name, label, etc.) |
-| `variables:` | Data connections and state storage |
-| `language:` | Locale configuration |
-| `start_agent` | Entry point subagent (exactly one required) |
-
-## Next Steps
-
-- [components/](../components/) - Reusable action and subagent templates
-- [patterns/](../patterns/) - Advanced patterns for complex behaviors
-- [metadata/](../metadata/) - XML metadata templates

package/skills/developing-agentforce/assets/agents/hello-world.agent

@@ -1,60 +0,0 @@
-# Hello World Agent
-# The minimal viable Agentforce agent - start here!
-#
-# This template shows the absolute minimum structure required for a working agent.
-# Use this as your starting point when learning Agent Script.
-#
-# ★ Why This Structure?
-#   - system: Sets agent personality and default messages
-#   - config: Required metadata for deployment (agent_name must be unique)
-#   - variables: Linked variables connect to Messaging context (required for deployment)
-#   - language: Locale settings (required for deployment)
-#   - start_agent: Entry point subagent (exactly one required)
-#
-# ★ Key Validation Points (from 100-point scoring):
-#   - [10 pts] config block with all 4 required fields
-#   - [10 pts] 3 linked variables (EndUserId, RoutableId, ContactId)
-#   - [5 pts] language block present
-#   - [10 pts] At least one start_agent subagent
-#
-# Deploy with: sf agent publish authoring-bundle --api-name Hello_World_Agent --target-org [alias]
-
-system:
-	instructions: "You are a friendly assistant. Greet users warmly and help them."
-	messages:
-		welcome: "Hello! I'm here to help. What can I do for you today?"
-		error: "I'm sorry, something went wrong. Please try again."
-
-config:
-	agent_name: "Hello_World_Agent"
-	default_agent_user: "your.user@company.com"
-	agent_label: "Hello World Agent"
-	description: "A minimal example agent to learn Agent Script basics"
-
-variables:
-	# Linked variables (required) - Connect to Salesforce Messaging context
-	EndUserId: linked string
-		source: @MessagingSession.MessagingEndUserId
-		description: "Messaging End User ID"
-	RoutableId: linked string
-		source: @MessagingSession.Id
-		description: "Messaging Session ID"
-	ContactId: linked string
-		source: @MessagingEndUser.ContactId
-		description: "Contact ID"
-
-language:
-	default_locale: "en_US"
-	additional_locales: ""
-	all_additional_locales: False
-
-# Entry point subagent - this is where every conversation starts
-start_agent main:
-	label: "Main"
-	description: "Greets users and provides help"
-
-	reasoning:
-		instructions: ->
-			| Welcome the user warmly.
-			| Ask how you can help them today.
-			| Be friendly and conversational.

package/skills/developing-agentforce/assets/agents/multi-subagent.agent

@@ -1,105 +0,0 @@
-# Multi-Subagent Agent Template
-# An agent with multiple conversation subagents (hub-and-spoke pattern)
-# Users are routed to specialized subagents based on their needs
-#
-# Usage: Replace {{placeholders}} with your values
-# Required: agent_name, default_agent_user, agent_label, description
-# Required: At least 2 subagents with label and description
-
-system:
-	instructions: "{{SystemInstructions}}"
-	messages:
-		welcome: "{{WelcomeMessage}}"
-		error: "I'm sorry, I encountered an issue. Please try again."
-
-config:
-	agent_name: "{{AgentApiName}}"
-	default_agent_user: "{{AgentUser}}"
-	agent_label: "{{AgentLabel}}"
-	description: "{{AgentDescription}}"
-
-variables:
-	EndUserId: linked string
-		source: @MessagingSession.MessagingEndUserId
-		description: "Messaging End User ID"
-	RoutableId: linked string
-		source: @MessagingSession.Id
-		description: "Messaging Session ID"
-	ContactId: linked string
-		source: @MessagingEndUser.ContactId
-		description: "Contact ID"
-	user_intent: mutable string
-		description: "What the user is trying to accomplish"
-
-language:
-	default_locale: "en_US"
-	additional_locales: ""
-	all_additional_locales: False
-
-start_agent agent_router:
-	label: "Subagent Router"
-	description: "Routes users to the appropriate subagent based on their needs"
-
-	reasoning:
-		instructions: ->
-			| Determine what the user needs help with.
-			| Route them to the most appropriate subagent.
-			| If unclear, ask clarifying questions.
-		actions:
-			go_to_subagent_one: @utils.transition to @subagent.{{subagent_one_name}}
-			go_to_subagent_two: @utils.transition to @subagent.{{subagent_two_name}}
-			go_to_subagent_three: @utils.transition to @subagent.{{subagent_three_name}}
-			go_to_farewell: @utils.transition to @subagent.farewell
-			go_to_escalation: @utils.transition to @subagent.escalation
-
-subagent {{subagent_one_name}}:
-	label: "{{SubagentOneLabel}}"
-	description: "{{SubagentOneDescription}}"
-
-	reasoning:
-		instructions: ->
-			| {{SubagentOneInstructions}}
-		actions:
-			back_to_menu: @utils.transition to @subagent.agent_router
-
-subagent {{subagent_two_name}}:
-	label: "{{SubagentTwoLabel}}"
-	description: "{{SubagentTwoDescription}}"
-
-	reasoning:
-		instructions: ->
-			| {{SubagentTwoInstructions}}
-		actions:
-			back_to_menu: @utils.transition to @subagent.agent_router
-
-subagent {{subagent_three_name}}:
-	label: "{{SubagentThreeLabel}}"
-	description: "{{SubagentThreeDescription}}"
-
-	reasoning:
-		instructions: ->
-			| {{SubagentThreeInstructions}}
-		actions:
-			back_to_menu: @utils.transition to @subagent.agent_router
-
-subagent farewell:
-	label: "Farewell"
-	description: "Ends the conversation gracefully"
-
-	reasoning:
-		instructions: ->
-			| Thank the user for reaching out.
-			| Wish them a great day.
-			| Let them know they can return anytime.
-
-subagent escalation:
-	label: "Escalation"
-	description: "Handles requests to transfer to a live human agent"
-
-	reasoning:
-		instructions: ->
-			| If the user explicitly asks to speak with a human, escalate.
-			| Acknowledge the request and transfer gracefully.
-		actions:
-			escalate_to_human: @utils.escalate
-				description: "Escalate to a human agent"

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

@@ -1,272 +0,0 @@
-# Order Service Agent
-# ========================
-#
-# A complex real-world agent for e-commerce customer service featuring:
-# - Verification gate before order access
-# - Multiple specialized subagents (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 agent_router:
-	description: "Route customers through verification then to the right subagent"
-	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 subagent:
-			- Order questions -> use to_orders
-			- Returns -> use to_returns
-			- Tracking -> use to_tracking
-		actions:
-			to_verify: @utils.transition to @subagent.verification
-				description: "Begin identity verification"
-			to_orders: @utils.transition to @subagent.order_status
-				description: "Check order status"
-				available when @variables.customer_verified == True
-			to_returns: @utils.transition to @subagent.returns
-				description: "Process a return"
-				available when @variables.customer_verified == True
-			to_tracking: @utils.transition to @subagent.shipment_tracking
-				description: "Track a shipment"
-				available when @variables.customer_verified == True
-
-subagent 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 @subagent.order_status
-				description: "Move to order lookup"
-				available when @variables.customer_verified == True
-
-			escalate_now: @utils.escalate
-				description: "Transfer to human agent"
-
-subagent 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 @subagent.returns
-				description: "Start a return"
-				available when @variables.order_status != ""
-
-			to_tracking: @utils.transition to @subagent.shipment_tracking
-				description: "Track shipment"
-				available when @variables.tracking_number != ""
-
-			back: @utils.transition to @subagent.agent_router
-				description: "Route to a different subagent"
-
-subagent 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 @subagent.agent_router
-				description: "Route to a different subagent"
-
-subagent 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 @subagent.agent_router
-				description: "Route to a different subagent"
-
-	after_reasoning: ->
-		if @variables.return_initiated == True:
-			transition to @subagent.follow_up
-
-subagent 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 @subagent.order_status
-				description: "Look up another order"
-			back: @utils.transition to @subagent.agent_router
-				description: "Start over"

package/skills/developing-agentforce/assets/agents/production-faq.agent

@@ -1,101 +0,0 @@
-# Simple FAQ Agent
-# A minimal working example of an Agentforce agent
-# Uses pure LLM reasoning without external actions
-#
-# Deploy with: sf agent publish authoring-bundle --api-name Simple_FAQ_Agent --target-org [alias]
-
-system:
-	instructions: "You are a helpful FAQ assistant for our company. Answer questions accurately and concisely. If you don't know the answer, say so honestly. Never share sensitive or confidential information. Keep responses friendly and professional."
-	messages:
-		welcome: "Hello! I'm your FAQ assistant. How can I help you today?"
-		error: "I'm sorry, I encountered an issue. Please try again."
-
-config:
-	agent_name: "Simple_FAQ_Agent"
-	default_agent_user: "agent.user@company.com"
-	agent_label: "Simple FAQ Agent"
-	description: "A minimal FAQ agent that answers common questions using AI"
-
-variables:
-	EndUserId: linked string
-		source: @MessagingSession.MessagingEndUserId
-		description: "Messaging End User ID"
-	RoutableId: linked string
-		source: @MessagingSession.Id
-		description: "Messaging Session ID"
-	ContactId: linked string
-		source: @MessagingEndUser.ContactId
-		description: "Contact ID"
-	user_question: mutable string
-		description: "The user's current question"
-	conversation_topic: mutable string
-		description: "The current subject being discussed"
-	question_count: mutable number
-		description: "Number of questions answered in this session"
-
-language:
-	default_locale: "en_US"
-	additional_locales: ""
-	all_additional_locales: False
-
-start_agent agent_router:
-	label: "Subagent Router"
-	description: "Routes incoming questions to the FAQ handler"
-
-	reasoning:
-		instructions: ->
-			| Listen to the user's question and determine how to help.
-			| If the question is about a specific subject, note it.
-			| Route to the FAQ handler for processing.
-		actions:
-			handle_faq: @utils.transition to @subagent.faq_handler
-			end_conversation: @utils.transition to @subagent.farewell
-
-subagent faq_handler:
-	label: "FAQ Handler"
-	description: "Handles frequently asked questions and provides helpful answers"
-
-	reasoning:
-		instructions: ->
-			| Answer the user's question based on your knowledge.
-			| Be helpful, accurate, and concise.
-			| Keep responses under 3-4 sentences when possible.
-			| If you need more information, ask clarifying questions.
-			|
-			| Common topics you can help with:
-			| - Business hours and location
-			| - Return and refund policies
-			| - Shipping information
-			| - Product questions
-			| - Account and billing
-			|
-			| If the question is outside your knowledge:
-			| - Acknowledge you don't have that information
-			| - Suggest contacting customer support
-			| - Offer to help with something else
-		actions:
-			new_question: @utils.transition to @subagent.agent_router
-			end_conversation: @utils.transition to @subagent.farewell
-			escalate: @utils.transition to @subagent.escalation
-
-subagent farewell:
-	label: "Farewell"
-	description: "Ends the conversation politely"
-
-	reasoning:
-		instructions: ->
-			| Thank the user for their questions.
-			| Wish them a great day.
-			| Let them know they can return anytime for more help.
-
-subagent escalation:
-	label: "Escalation"
-	description: "Handles requests to speak with a human agent"
-
-	reasoning:
-		instructions: ->
-			| If the user wants to speak with a human, escalate gracefully.
-			| Acknowledge their request and transfer the conversation.
-		actions:
-			escalate_to_human: @utils.escalate
-				description: "Transfer to a human agent"

package/skills/developing-agentforce/assets/agents/production-faq.bundle-meta.xml

@@ -1,4 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
-  <bundleType>AGENT</bundleType>
-</AiAuthoringBundle>