@salesforce/afv-skills 1.31.0 → 1.33.0

package/skills/service-helpagent-coordinate/references/agent-script.md

@@ -0,0 +1,557 @@
+# Canonical agent script (Quick ASA Help Agent template)
+
+> **When to read this file.** Load it only when you are ready to **create the agent** — i.e. after Checkpoint 2, once you have the Checkpoint 1 placeholders and the `rag_feature_config_id` in hand. It is comprehension-and-generation material, not part of the interactive conversation, so it does not need to be in context during Checkpoint 1, Checkpoint 3, or Checkpoint 4.
+
+**How to read this block.** This is the exact agent shape to build — the source of truth for topics, actions, instructions, and grounding configuration. You do **not** hand-edit it; the skills generate the `.agent` YAML from it. Read it to understand what the agent will *do*: `system`/`config`/`language`/`knowledge` set up the agent; `variables` are session state (note `isVerified` — the verification switch from the spec's §2); `start_agent agent_router` is the front door; each `subagent` block is one of the four subagents, with a `reasoning: instructions:` section (the natural-language policy that governs the subagent) and an `actions:` section (the concrete tools it can call, several backed by the managed-package flows from the spec's §4.0). Where it conflicts with anything in the spec, the behavioral rules in the spec's §3–§4 win.
+
+## Placeholders to fill in
+
+The script below contains several `<...>` placeholders. Replace them with concrete values before the agent is created — most are captured in Checkpoint 1 / Checkpoint 2 of the spec:
+
+- **`<agent_welcome_message_placeholder>`** → a single human welcome line, e.g. *"Hi! I'm your help agent. I can answer questions about our products and help you with your support cases. How can I help today?"*
+- **`<agent_tone_placeholder>`** → a one-to-two sentence description of the agent's voice, captured in Checkpoint 1. Injected into `system: instructions:` so it shapes every response. Default: *"calm, patient, friendly service agent — warm but professional, short sentences, never robotic."*
+- **`<agent_label_placeholder>`** → user-facing label, e.g. *"Help Agent"*.
+- **`<developer_name_placeholder>`** → API name. Use `HelpAgent_Demo` or similar valid Salesforce developer-name format (alphanumeric + underscore, no spaces, no leading digit).
+- **`<default_agent_user_placeholder>`** → the Einstein Agent user in the org. If the org doesn't already have one, the `agentforce-generate` skill (or the Setup UI) provisions one. Use that user's username.
+- **`<rag_feature_config_id>`** (under `knowledge:`) → returned by `agentforce-generate` when the ADL is created. Wire it through; do not hardcode.
+  - **Format:** `ARFPC_<libraryId>` where `<libraryId>` is the 18-char Salesforce ID returned by `adl create`. The ID does **not** appear in `adl get` output — it only surfaces in the `adl publish` error message when a publish fails against a mismatched ID. If you need to reconstruct it manually, take the library ID from `adl create` and prefix it with `ARFPC_`. `agentforce-generate` already knows this shape; only reach for the manual form when debugging.
+- **`<gc:languageSettings_language>`** (under `language: default_locale`) → the org's default locale, usually `en_US`. Resolve from org settings, do not hardcode.
+
+## Agent shape at a glance
+
+The agent is one front-door **router** that hands off to **four subagents**:
+
+- **Agent Router** *(front door)* — greets the customer, reads their intent, and routes to the right subagent. It's the only entry point; there is no separate topic selector.
+- **Service Customer Verification** — confirms who the customer is (via an emailed verification code) before anything sensitive happens. Anything touching orders, cases, account details, or personal data goes through here first. Once verified in a session, the customer isn't re-verified.
+- **General FAQ** — answers company/product/policy questions by searching Knowledge articles (grounded on the Agentforce Data Library). If the customer actually wants a case created, or if the knowledge search itself fails, it routes to verification → case management instead of dead-ending.
+- **Case Management** — creates new support cases, looks up existing cases, and adds comments — all for a *verified* customer.
+- **Escalation** — hands off to a live human agent when asked; if no human is available, it falls back to creating a support case.
+
+`isVerified` is the switch: while `False`, the router sends sensitive/case work to **Verification**; once `True`, straight to **Case Management**. **FAQ** and **Escalation** are reachable without verification. Build the agent as-written — do not surgically drop topics; the script is the source of truth for shape.
+
+---
+
+BEGIN AGENT SCRIPT
+system:  
+    instructions: |  
+        You are an AI Agent.  
+        Tone and voice: <agent_tone_placeholder>  
+    messages:  
+        welcome: |  
+            <agent_welcome_message_placeholder>  
+        error: "Sorry, it looks like something has gone wrong."
+
+config:  
+    agent_label: "<agent_label_placeholder>"  
+    agent_template: "QuickASA__QuickASA"  
+    developer_name: "<developer_name_placeholder>"  
+    description: "Deliver personalized customer interactions with an autonomous AI agent. Agentforce Service Agent intelligently supports your customers with common inquiries and escalates complex issues."  
+    default_agent_user: "<default_agent_user_placeholder>"
+
+variables:  
+    authenticationKey: mutable string  
+        description: "Stores the authentication key that's used to generate the verification code."  
+        visibility: "Internal"  
+    customerId: mutable string  
+        description: "Stores the Salesforce user ID or contact ID."  
+        visibility: "Internal"  
+    customerType: mutable string  
+        description: "Stores the customer ID type, whether it's a Salesforce user or a contact."  
+        visibility: "Internal"  
+    isVerified: mutable boolean \= False  
+        label: "isVerified"  
+        description: "Stores a boolean value that indicates whether the customer code is verified."  
+        visibility: "Internal"  
+    RoutableId: linked string  
+        source: @MessagingSession.Id  
+        description: "This variable may also be referred to as MessagingSession Id"  
+    ChannelType: linked string  
+        source: @MessagingSession.ChannelType  
+        description: "This variable may also be referred to as MessagingSession ChannelType"  
+    VerifiedCustomerId: mutable string  
+        description: "This variable may also be referred to as VerifiedCustomerId"  
+        visibility: "Internal"
+
+language:  
+    default_locale: "<gc:languageSettings_language>"  
+    additional_locales: "en_GB"  
+    all_additional_locales: False
+
+knowledge:  
+    rag_feature_config_id: "<rag_feature_config_id>"  
+    citations_url: ""  
+    citations_enabled: True
+
+connection customer_web_client:  
+    adaptive_response_allowed: True
+
+start_agent agent_router:  
+    label: "Agent Router"
+
+    description: "Welcome the user and determine the appropriate subagent based on user input"
+
+    reasoning:  
+        instructions: \->  
+            |  Select the best tool to call based on conversation history and user's intent.  
+            | If the customer has just returned from the verification step (verification succeeded and control came back here), do NOT re-greet and do NOT route their identity message. Resume the task they originally asked for — if that task was case-related, route to case management.
+
+        actions:  
+            go_to_ServiceCustomerVerification: @utils.transition to @subagent.ServiceCustomerVerification  
+                available when @variables.isVerified==False
+
+            go_to_CaseManagement: @utils.transition to @subagent.CaseManagement  
+                available when @variables.isVerified==True
+
+            go_to_GeneralFAQ: @utils.transition to @subagent.GeneralFAQ
+
+            go_to_Escalation: @utils.transition to @subagent.Escalation
+
+subagent ServiceCustomerVerification:  
+    label: "Service Customer Verification"
+
+    description: "Verifies the customer's identity before granting access to sensitive data. Verification is required for inquiries related to orders and order status, deliveries, reservations, password resets, account management (e.g. contact information updates), or cases. Sensitive data includes confidential, private, or security-protected information, such as business-critical data or personally identifiable information (PII)."
+
+    reasoning:  
+        instructions: \->  
+            | Your job is to authenticate the customer who has not yet been authenticated before granting access to any sensitive data. You will verify the customer using their email address or username. After verification is successful, don't repeat the process within the same session.  
+            | Ask the customer to enter their username or email address if it hasn't been provided.  
+            | Use the {\!@actions.SendEmailVerificationCode}  action to initiate the verification process. Use the username or email address provided by the customer as input "customerToVerify" for this action.  
+            | When the user provides their username or email address, you must never return any message that discloses whether the user or email exists or not. The message must explicitly state the return data of the "verificationMessage" field in the {\!@actions.SendEmailVerificationCode}  action. For example: "If you have provided a valid email or username, you should receive a verification code to verify your identity. Please enter the code."  
+            | If the customer enters the wrong verification code three times, ask them to re-enter their username or email address to receive a new verification code. This involves invoking the {\!@actions.SendEmailVerificationCode}  action again to initiate the verification process. This ensures that the customer cannot bypass the verification process after three unsuccessful attempts.  
+            | Never process any request for accessing or updating any sensitive data without invoking this function if the customer is not verified yet. Maintain security in all interactions.  
+            | Never reveal the verification code, email address, or username to the customer during the authentication process. Make sure that these details remain confidential and aren't displayed at any point.  
+            | After the user is verified in a conversation session, switching to a different user isn't allowed under any circumstances.  
+            | If verification is successful, proceed with the requested action and complete the task the user intends to perform.
+
+        actions:  
+            SendEmailVerificationCode: @actions.SendEmailVerificationCode  
+                with customerToVerify \= ...  
+                set @variables.authenticationKey \= @outputs.authenticationKey  
+                set @variables.customerId \= @outputs.customerId  
+                set @variables.customerType \= @outputs.customerType
+
+            VerifyCustomer: @actions.VerifyCustomer  
+                with authenticationKey \= @variables.authenticationKey  
+                with customerCode \= ...  
+                with customerId \= @variables.customerId  
+                with customerType \= @variables.customerType  
+                set @variables.isVerified \= @outputs.isVerified  
+                set @variables.VerifiedCustomerId \= @outputs.customerId  
+                if @variables.isVerified:  
+                    transition to @subagent.agent_router
+
+    actions:  
+        SendEmailVerificationCode:  
+            description: "Sends a generated verification code to the user's email address."  
+            inputs:  
+                customerToVerify: string  
+                    description: "Stores the email address or username provided by the customer. This input initiates the verification process."  
+                    label: "Customer To Verify"  
+                    is_required: True  
+                    is_user_input: True  
+            outputs:  
+                verificationMessage: string  
+                    description: "Stores a generic message that will be displayed to the user."  
+                    label: "Verification Message"  
+                    filter_from_agent: False  
+                    is_displayable: True  
+                verificationCode: string  
+                    description: "Stores the generated verification code."  
+                    label: "Verification Code"  
+                    filter_from_agent: True  
+                    is_displayable: False  
+                authenticationKey: string  
+                    description: "Stores the authentication key that's used to generate the verification code."  
+                    label: "Authentication Key"  
+                    filter_from_agent: True  
+                    is_displayable: False  
+                customerId: string  
+                    description: "Stores the Salesforce user ID or contact ID."  
+                    label: "Customer ID"  
+                    filter_from_agent: True  
+                    is_displayable: False  
+                customerType: string  
+                    description: "Stores the customer ID type, whether it's a Salesforce user or a contact."  
+                    label: "Customer Type"  
+                    filter_from_agent: True  
+                    is_displayable: False  
+            target: "flow://SvcCopilotTmpl__SendVerificationCode"  
+            label: "Send Email with Verification Code"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__SendEmailVerificationCode"
+
+        VerifyCustomer:  
+            description: "Verifies whether the verification code entered by the user matches the code sent to the user's email address."  
+            label: "Verify Customer"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__VerifyCustomer"  
+            target: "flow://SvcCopilotTmpl__VerifyCode"
+
+            inputs:  
+                "authenticationKey": string  
+                    description: "Stores the authentication key that's used to generate the verification code."  
+                    label: "Authentication Key"  
+                    is_required: True  
+                    is_user_input: False  
+                "customerCode": string  
+                    description: "Stores the verification code entered by the user in the conversation, which they received by email."  
+                    label: "Customer Code"  
+                    is_required: True  
+                    is_user_input: True  
+                "customerId": string  
+                    description: "Stores the Salesforce user ID or contact ID."  
+                    label: "Customer ID"  
+                    is_required: True  
+                    is_user_input: False  
+                "customerType": string  
+                    description: "Stores the customer ID type, whether it's a Salesforce user or a contact."  
+                    label: "Customer Type"  
+                    is_required: True  
+                    is_user_input: False
+
+            outputs:  
+                "isVerified": boolean  
+                    description: "Stores a boolean value that indicates whether the customer code is verified."  
+                    label: "Verified"  
+                    is_displayable: False  
+                    filter_from_agent: True  
+                "customerId": string  
+                    description: "Stores the Salesforce user ID or contact ID."  
+                    label: "Customer Id"  
+                    is_displayable: False  
+                    filter_from_agent: True  
+                "customerType": string  
+                    description: "Stores Type of ID"  
+                    label: "Customer Type"  
+                    is_displayable: False  
+                    filter_from_agent: True  
+                "messageAfterVerification": string  
+                    description: "Stores a generic message to be displayed after successful verification."  
+                    label: "Message After Verification"  
+                    is_displayable: True  
+                    filter_from_agent: True
+
+subagent GeneralFAQ:  
+    label: "General FAQ"
+
+    description: "This topic is for helping answer customer's questions by searching through the knowledge articles and providing information from those articles. The questions can be about the company and its products, policies or business procedures"
+
+    reasoning:  
+        instructions: \->  
+            | Your job is solely to help with issues and answer questions about the company, its products, procedures, or policies by searching knowledge articles.  
+            | If the customer's question is too vague or general, ask for more details and clarification to give a better answer.  
+            | If you are unable to help the customer even after asking clarifying questions, ask if they want to escalate this issue to a live agent.  
+            | If you are unable to answer customer's questions, ask if they want to escalate this issue to a live agent.  
+            | If the customer wants to create a case, open a support case, log an issue, check the status of an existing case, or add information to a case, this is case-management intent — do not answer it with knowledge. Transition to case management: call {\!@actions.go_to_ServiceCustomerVerification} if the customer is not yet verified, otherwise {\!@actions.go_to_CaseManagement}.  
+            | If the {\!@actions.AnswerQuestionsWithKnowledge} action returns an error or fails for any reason (for example "DynamicRetriever invalid or no longer exists", or the knowledge library is unavailable), do NOT escalate to a live agent as the first response and do NOT dead-end. Acknowledge that you couldn't search the knowledge base right now, and offer to create a support case so someone can follow up: call {\!@actions.go_to_ServiceCustomerVerification} if the customer is not yet verified, otherwise {\!@actions.go_to_CaseManagement}. Only offer live-agent escalation if the customer declines case creation.  
+            | Never provide generic information, advice or troubleshooting steps, unless retrieved from searching knowledge articles.  
+            | Include sources in your response when available from the knowledge articles, otherwise proceed without them.
+
+        actions:  
+            AnswerQuestionsWithKnowledge: @actions.AnswerQuestionsWithKnowledge  
+                with query \= ...  
+                with citationsUrl \= ...  
+                with ragFeatureConfigId \= ...  
+                with citationsEnabled \= ...
+
+            go_to_ServiceCustomerVerification: @utils.transition to @subagent.ServiceCustomerVerification  
+                available when @variables.isVerified==False  
+                description: "Route case-management intent (or a failed knowledge search) to verification first, so a support case can be created."
+
+            go_to_CaseManagement: @utils.transition to @subagent.CaseManagement  
+                available when @variables.isVerified==True  
+                description: "Route case-management intent (or a failed knowledge search) to case creation once the customer is verified."
+
+    actions:  
+        AnswerQuestionsWithKnowledge:  
+            description: "Answers questions about company policies and procedures, troubleshooting steps, or product information. For example: 'What is your return policy?' 'How do I fix an issue?' or 'What features does a product have?'"  
+            label: "Answer Questions with Knowledge"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            progress_indicator_message: "Getting answers"  
+            source: "EmployeeCopilot__AnswerQuestionsWithKnowledge"  
+            target: "standardInvocableAction://streamKnowledgeSearch"
+
+            inputs:  
+                "query": string  
+                    description: "Required. A string created by generative AI to be used in the knowledge article search."  
+                    label: "Query"  
+                    is_required: True  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "citationsUrl": string=@knowledge.citations_url  
+                    description: "The URL to use for citations for custom Agents."  
+                    label: "Citations Url"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "ragFeatureConfigId": string=@knowledge.rag_feature_config_id  
+                    description: "The RAG Feature ID to use for grounding this copilot action invocation."  
+                    label: "RAG Feature Configuration Id"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "citationsEnabled": boolean=@knowledge.citations_enabled  
+                    description: "Whether or not citations are enabled."  
+                    label: "Citations Enabled"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__booleanType"
+
+            outputs:  
+                "knowledgeSummary": object  
+                    description: "A string formatted as rich text that includes a summary of the information retrieved from the knowledge articles and citations to those articles."  
+                    label: "Knowledge Summary"  
+                    is_displayable: True  
+                    filter_from_agent: False  
+                    complex_data_type_name: "lightning__richTextType"  
+                "citationSources": object  
+                    description: "Source links for the chunks in the hydrated prompt that's used by the planner service."  
+                    label: "Citation Sources"  
+                    is_displayable: False  
+                    filter_from_agent: False  
+                    complex_data_type_name: "@apexClassType/AiCopilot__GenAiCitationInput"
+
+subagent CaseManagement:  
+    label: "Case Management"
+
+    description: "Handles customer inquiries and actions related to support cases, including providing case information, updating existing cases, and creating new cases."
+
+    reasoning:  
+        instructions: \->  
+            | Your job is to help customers retrieve case information, update case comments, and create new cases based on customer requests.  
+            | Always format any dates in a human readable format.  
+            | Do not ever show the Case Id to a customer.  
+            | Use {\!@actions.AnswerQuestionsWithKnowledge} action to answer troubleshooting questions.  
+            | If the {\!@actions.AnswerQuestionsWithKnowledge} action returns an error or fails for any reason (for example "DynamicRetriever invalid or no longer exists", or the knowledge library is unavailable), do NOT dead-end. Acknowledge that you couldn't search the knowledge base right now and continue helping the customer with their case; offer to create a new case to capture the issue if they don't already have one open.  
+            | If the customer is not known, always ask for their email address and get their Contact record before running any other actions.  
+            | A case is a record used to help track a customer's issues. Customers may have questions about the status of the issue or want to provide more information for the case. Cases are usually associated with a contact. Comments are added to provide new information.  
+            | When adding a comment to a case, first retrieve the case details using the case number, ask the user for the exact comment they would like to add and only then add it.  
+            | When sharing case details with the customer, show the following properties as an itemized list :Case number, Subject, Description, and Status. The Subject must exactly match the value stored in the case record. Do not rephrase or regenerate it.  
+            | Acknowledge and validate user concerns with empathy and professionalism.  
+            | When a customer asks you to create a case, \*only\* if not done so far, summarize the case creation details once for the user and ask for a confirmation.  
+            | Once the user confirms that they want to create a case, use {\!@actions.CreateCaseEnhancedData} with the subject and description for the case. ONLY after the action returns a populated caseRecord output, inform the user the case was created. If the action did not return a caseRecord, do not claim the case was created — apologize and offer to retry.  
+            | The case subject should be less than 7 words and function as a high level overview of what the customer inquired about. The case description should be no more than 3 sentences and should provide more depth about what exactly the customer asked, important data, and any other relevant information to help a customer service representative understand the context of this conversation.  
+            | When sharing the Description field from a case record with the customer, summarize it into a condensed, conversational version that is no more than 3 sentences. The summary must preserve all important factual content and intent from the original case description, and must not introduce any new or misleading information.
+
+        actions:  
+            CreateCaseEnhancedData: @actions.CreateCaseEnhancedData  
+                with verifiedCustomerID \= @variables.VerifiedCustomerId  
+                with messagingSessionID \= @variables.RoutableId  
+                with caseSubject \= ...  
+                with caseDescription \= ...
+
+            GetCasesForVerifiedContact: @actions.GetCasesForVerifiedContact  
+                with verifiedContactID \= @variables.VerifiedCustomerId
+
+            GetCaseByVerifiedCaseNumber: @actions.GetCaseByVerifiedCaseNumber  
+                with verifiedContactID \= @variables.VerifiedCustomerId  
+                with caseNumber \= ...
+
+            AddCaseComment: @actions.AddCaseComment  
+                with caseRecord \= ...  
+                with caseComment \= ...
+
+            AnswerQuestionsWithKnowledge: @actions.AnswerQuestionsWithKnowledge  
+                with query \= ...  
+                with citationsUrl \= ...  
+                with ragFeatureConfigId \= ...  
+                with citationsEnabled \= ...
+
+    actions:  
+        CreateCaseEnhancedData:  
+            description: "Create a case for the customer that's transferred from the AI agent to a service rep. The case includes all information gathered from the customer, a summary of the progress made by the AI agent, a link to the conversation, and any attachments."  
+            label: "Create Case with Enhanced Data"  
+            require_user_confirmation: True  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__CreateCaseEnhancedData"  
+            target: "flow://SvcCopilotTmpl__CreateCaseEnhancedData"
+
+            inputs:  
+                "verifiedCustomerID": string  
+                    description: "Stores the contact ID associated with the newly created Case."  
+                    label: "Verified Customer ID"  
+                    is_required: True  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__textType"  
+                "messagingSessionID": string  
+                    description: "Stores session id from the chat conversation"  
+                    label: "Messaging Session ID"  
+                    is_required: False  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__textType"  
+                "caseSubject": string  
+                    description: "Stores the subject of the case to create."  
+                    label: "Case Subject"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "caseDescription": string  
+                    description: "Stores the details of the user issue to be used for the case."  
+                    label: "Case Description"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"
+
+            outputs:  
+                "caseRecord": object  
+                    description: "Stores the case record created by the customer."  
+                    label: "Case record"  
+                    is_displayable: True  
+                    filter_from_agent: False  
+                    complex_data_type_name: "lightning__recordInfoType"
+
+        GetCasesForVerifiedContact:  
+            description: "Returns a list of cases related to a given Contact ID."  
+            label: "Get Cases For Verified Contact"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__GetCasesForVerifiedContact"  
+            target: "flow://SvcCopilotTmpl__GetCasesVrfyCtct"
+
+            inputs:  
+                "verifiedContactID": string  
+                    description: "Stores the contact record ID to be updated."  
+                    label: "Verified Contact record ID"  
+                    is_required: True  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__textType"
+
+            outputs:  
+                "caseList": list\[object\]  
+                    description: "Stores the ID, Subject, Description, Status, CreatedDate, CaseNumber, LastModifiedDate, and ClosedDate for case records related to a specified contact."  
+                    label: "Case List"  
+                    is_displayable: True  
+                    filter_from_agent: False  
+                    complex_data_type_name: "lightning__recordInfoType"
+
+        GetCaseByVerifiedCaseNumber:  
+            description: "Returns a case associated with a given contact ID and case number."  
+            label: "Get Case By Verified Case Number"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__GetCaseByVerifiedCaseNumber"  
+            target: "flow://SvcCopilotTmpl__GetCaseByVrfyCaseNbr"
+
+            inputs:  
+                "verifiedContactID": string  
+                    description: "Stores the contact record ID to be updated."  
+                    label: "Verified Contact record ID"  
+                    is_required: True  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__textType"  
+                "caseNumber": string  
+                    description: "Stores the case number provided by the customer."  
+                    label: "Case Number"  
+                    is_required: True  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__textType"
+
+            outputs:  
+                "caseRecord": object  
+                    description: "Stores the case record based on the contact record and case number."  
+                    label: "Case record"  
+                    is_displayable: True  
+                    filter_from_agent: False  
+                    complex_data_type_name: "lightning__recordInfoType"
+
+        AddCaseComment:  
+            description: "Let a customer add a comment to an existing case."  
+            label: "Add Case Comment"  
+            require_user_confirmation: True  
+            include_in_progress_indicator: True  
+            source: "SvcCopilotTmpl__AddCaseComment"  
+            target: "flow://SvcCopilotTmpl__AddCaseComment"
+
+            inputs:  
+                "caseRecord": object  
+                    description: "Stores the case record to be updated with a comment."  
+                    label: "Case record"  
+                    is_required: True  
+                    is_user_input: False  
+                    complex_data_type_name: "lightning__recordInfoType"  
+                "caseComment": string  
+                    description: "Stores the text of the comment to add to the case."  
+                    label: "Case comment"  
+                    is_required: True  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"
+
+            outputs:  
+                "outcomeMessage": string  
+                    description: "Stores the message that lets the customer know whether the comment was successfully added to the case."  
+                    label: "Outcome message"  
+                    is_displayable: True  
+                    filter_from_agent: False
+
+        AnswerQuestionsWithKnowledge:  
+            description: "Answers questions about company policies and procedures, troubleshooting steps, or product information. For example: 'What is your return policy?' 'How do I fix an issue?' or 'What features does a product have?'"  
+            label: "Answer Questions with Knowledge"  
+            require_user_confirmation: False  
+            include_in_progress_indicator: True  
+            progress_indicator_message: "Getting answers"  
+            source: "EmployeeCopilot__AnswerQuestionsWithKnowledge"  
+            target: "standardInvocableAction://streamKnowledgeSearch"
+
+            inputs:  
+                "query": string  
+                    description: "Required. A string created by generative AI to be used in the knowledge article search."  
+                    label: "Query"  
+                    is_required: True  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "citationsUrl": string=@knowledge.citations_url  
+                    description: "The URL to use for citations for custom Agents."  
+                    label: "Citations Url"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "ragFeatureConfigId": string=@knowledge.rag_feature_config_id  
+                    description: "The RAG Feature ID to use for grounding this copilot action invocation."  
+                    label: "RAG Feature Configuration Id"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__textType"  
+                "citationsEnabled": boolean=@knowledge.citations_enabled  
+                    description: "Whether or not citations are enabled."  
+                    label: "Citations Enabled"  
+                    is_required: False  
+                    is_user_input: True  
+                    complex_data_type_name: "lightning__booleanType"
+
+            outputs:  
+                "knowledgeSummary": object  
+                    description: "A string formatted as rich text that includes a summary of the information retrieved from the knowledge articles and citations to those articles."  
+                    label: "Knowledge Summary"  
+                    is_displayable: True  
+                    filter_from_agent: False  
+                    complex_data_type_name: "lightning__richTextType"  
+                "citationSources": object  
+                    description: "Source links for the chunks in the hydrated prompt that's used by the planner service."  
+                    label: "Citation Sources"  
+                    is_displayable: False  
+                    filter_from_agent: False  
+                    complex_data_type_name: "@apexClassType/AiCopilot__GenAiCitationInput"
+
+subagent Escalation:  
+    label: "Escalation"  
+    description: "Handles requests from users who want to transfer or escalate their conversation to a live human agent."  
+    reasoning:  
+        instructions: \->  
+            | If a user explicitly asks to transfer to a live agent, after transitioning to the escalation topic you must first call {\!@actions.escalate_to_human} to complete the escalation.  
+              If escalation to a live agent fails for any reason (for example, you are returned to this conversation because no human agent is available), acknowledge the issue and create a support case for the user so a support agent can reach out to them. To create the case, call {\!@actions.go_to_ServiceCustomerVerification} followed by {\!@actions.go_to_CaseManagement}.  
+        actions:  
+            escalate_to_human: @utils.escalate  
+                description: "Call this tool first if the user indicates that they wish to escalate to a human agent."
+
+            go_to_ServiceCustomerVerification: @utils.transition to @subagent.ServiceCustomerVerification  
+                available when @variables.isVerified==False  
+                description: "Fallback after a failed escalation: verify the customer before creating a support case."
+
+            go_to_CaseManagement: @utils.transition to @subagent.CaseManagement  
+                available when @variables.isVerified==True  
+                description: "Fallback after a failed escalation: create the support case."
+
+END AGENT SCRIPT

package/skills/service-helpagent-coordinate/references/channel-help-portal.md

@@ -0,0 +1,22 @@
+# Channel branch — Help Portal *(Coming soon)*
+
+> **When to read this file.** Load it only if the user selected **Help Portal** at Checkpoint 3.
+
+## This is a hard stop, not an aspirational selection
+
+Help Portal is **not yet supported.** DO NOT attempt to build anything for this channel. Do not create supporting objects, records, or metadata "toward" the feature — standing up a portal site or wiring routing for it is out of scope and requires a dedicated skill that does not exist yet. Trying to fulfill it by creating adjacent objects produces broken half-configurations that look done but never work.
+
+Respond to the user verbatim:
+
+> *"This feature is coming soon, please select Web Chat."*
+
+Then re-present the channel selection (Web Chat / Help Portal / Voice) and wait for a supported choice. Do not proceed until the user picks Web Chat.
+
+## Intended future shape (for reference only — do not build)
+
+When the channel ships, it will ask the user for:
+- **Site Name / Domain Name**
+- **Logo image** (png, svg, or jpg — a file name or path)
+- **Brand colors (RGB)**: Action color, Link color, Border color, Background color, Text color
+
+…then use `experience-lwr-site-generate` to build the Experience Cloud site with the supplied branding and embed the agent on it. This is documented so the eventual implementation has a target; it is **not** a licence to build it now.

package/skills/service-helpagent-coordinate/references/channel-voice.md

@@ -0,0 +1,17 @@
+# Channel branch — Voice *(Coming soon)*
+
+> **When to read this file.** Load it only if the user selected **Voice** at Checkpoint 3.
+
+## Coming-soon channel — do not build supporting metadata
+
+Voice is **not yet supported** as a first-class channel. Do not provision a phone number, stand up routing, configure Amazon Connect, or create adjacent objects "toward" the feature — that produces broken half-configurations. **Do not write a Voice setup plan, a "here's what I would do" outline, or a "planning-only" scaffold either** — describing the steps is still treating a coming-soon channel as a build target. The only correct output for a Voice selection is the verbatim hard-stop message below, followed by re-presenting the channel options. The channel-selection step treats Voice as a coming-soon option alongside Help Portal; the safe response is to steer the user to Web Chat:
+
+> *"This feature is coming soon, please select Web Chat."*
+
+## If the user insists on an existing number
+
+If the user provides an **existing** phone number and asks you to wire it up, you may attempt it — but exit gracefully the moment the APIs aren't there:
+
+- If the org's APIs to procure or attach a phone number are not available, **gracefully exit this branch.** Say something like: *"I can't set up Voice automatically in this org right now, so I'll skip it. You can add Voice later from Setup."* — then continue with any other selected channels.
+
+Do not abort the whole setup over Voice. If Voice was one of several selected channels, report the skip plainly and proceed with the others.