# Voice + Knowledge-Grounded Agent
# ================================
#
# A voice-channel service agent that answers caller questions by searching an
# Agentforce Data Library (ADL) via the AnswerQuestionsWithKnowledge action.
# This is the Project Codey "Steel Thread 2" shape: voice + knowledge grounding.
#
# Combines:
#   - modality voice:  (platform default voice — customize later in Agent Builder)
#   - VoiceCallId linked variable + connection messaging/customer_web_client
#   - knowledge: block + AnswerQuestionsWithKnowledge action
#
# Replace ARFPC_<libraryId> below with the value computed from your provisioned
# ADL: rag_feature_config_id = "ARFPC_" + libraryId.
# See references/data-library-reference.md for provisioning.

system:
    instructions: "You are a voice-based AI customer service agent. Keep responses brief — callers are listening, not reading. Answer questions ONLY from the knowledge base; never guess or read out information you did not retrieve. Never read out URLs, citations, or visual formatting — summarize what matters instead. Read back critical data before acting on it."
    messages:
        welcome: "Hi, thanks for calling! What can I help you with today?"
        error: "I'm sorry, I'm having trouble with that right now. Could you say that again?"

access:
    default_agent_user: "agent@example.com"

config:
    developer_name: "VoiceKnowledgeAgent"
    agent_label: "Voice Knowledge Agent"
    description: "Voice-channel service agent that answers caller questions grounded on an Agentforce Data Library"
    agent_type: "AgentforceServiceAgent"

variables:
    EndUserId: linked string
        source: @MessagingSession.MessagingEndUserId
        description: "End user identifier"
    RoutableId: linked string
        source: @MessagingSession.Id
        description: "Routable session identifier"
    ContactId: linked string
        source: @MessagingEndUser.ContactId
        description: "Contact record identifier"
    VoiceCallId: linked string
        source: @VoiceCall.Id
        description: "This variable may also be referred to as Voice Call Id"

knowledge:
    rag_feature_config_id: "ARFPC_<libraryId>"
    citations_enabled: True
    citations_url: ""

language:
    default_locale: "en_US"
    additional_locales: ""
    all_additional_locales: False

# Minimum voice config: platform default voice ("Mark", en_US) + core tuning.
# Optional advanced settings (filler-word detection, speak-up prompts, endpointing)
# are documented in references/voice-modality-reference.md — add them only if needed.
# Customize the voice later in Agent Builder → Connections → Voice.
modality voice:
    voice_id: "UgBBYS2sOqTuMpoF3BR0"
    outbound_speed: 1
    outbound_stability: 0.65
    outbound_similarity: 0.75

# customer_web_client (ECv2) is the voice-capable surface. connection messaging is
# additive here — kept because this agent escalates to a human (@utils.escalate).
connection customer_web_client:
    adaptive_response_allowed: True

connection messaging:
    escalation_message: "Let me transfer you to a specialist who can help with that."

start_agent agent_router:
    description: "Welcomes the caller and routes to the appropriate topic"
    reasoning:
        instructions: ->
            | Listen to what the caller needs and route them to the right topic.
            | For questions about products, policies, procedures, or troubleshooting, go to knowledge answers.
            | If the caller asks to speak with a person or you cannot help, escalate.
            | Do NOT answer questions directly — route to the appropriate topic.
        actions:
            go_knowledge: @utils.transition to @subagent.knowledge_answers
                description: "Route to knowledge answers for product, policy, or how-to questions"
            go_escalation: @utils.transition to @subagent.escalation
                description: "Transfer to a human agent"

subagent knowledge_answers:
    description: "Answers caller questions by searching the knowledge base"
    reasoning:
        instructions: ->
            | If the question is unclear, ask one short clarifying question first.
            | For every substantive question, call AnswerQuestionsWithKnowledge
              before answering.
            | Answer only from the returned knowledge summary, using one or two
              spoken sentences.
            | If the summary is empty, say the knowledge base has no answer and
              use {!@actions.go_escalation}.
            | Never speak URLs, citations, or list formatting. Offer to send
              returned links instead.
            | After answering, ask if there's anything else you can help with.
        actions:
            AnswerQuestionsWithKnowledge: @actions.AnswerQuestionsWithKnowledge
                with query = ...
                with citationsUrl = ...
                with ragFeatureConfigId = ...
                with citationsEnabled = ...
            go_escalation: @utils.transition to @subagent.escalation
                description: "Transfer to a human agent when the knowledge base has no answer or the caller asks for a person"
            go_back: @utils.transition to @subagent.agent_router
                description: "Return to main routing when the caller has a different question"

    actions:
        AnswerQuestionsWithKnowledge:
            description: "Answers questions about company policies, procedures, troubleshooting, or product information by searching knowledge articles. For example: 'What is your return policy?' or 'How do I fix an issue?'"
            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
                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
                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
                citationsEnabled: boolean = @knowledge.citations_enabled
                    description: "Whether or not citations are enabled."
                    label: "Citations Enabled"
                    is_required: False
                    is_user_input: True
            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"
                    complex_data_type_name: "lightning__richTextType"
                    filter_from_agent: False
                    is_displayable: True
                citationSources: object
                    description: "Source links for the chunks in the hydrated prompt that's used by the planner service."
                    label: "Citation Sources"
                    complex_data_type_name: "@apexClassType/AiCopilot__GenAiCitationInput"
                    filter_from_agent: False
                    is_displayable: False
            target: "standardInvocableAction://streamKnowledgeSearch"
            label: "Answer Questions with Knowledge"
            require_user_confirmation: False
            include_in_progress_indicator: True
            progress_indicator_message: "Let me check on that for you"
            source: "EmployeeCopilot__AnswerQuestionsWithKnowledge"

subagent escalation:
    description: "Transfers the caller to a live human agent"
    reasoning:
        instructions: ->
            | The caller needs to speak with a human agent. Use {!@actions.escalate_to_human} to transfer them.
            | Before transferring, briefly let them know you're connecting them.
        actions:
            escalate_to_human: @utils.escalate
                description: "Transfer the caller to a live agent"