# Copyright 2026 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # https://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Central repository for all migration prompts to ensure easy iteration and \ version control.""" from pathlib import Path # Inline copy of examples/bella_notte/agents/Bella_Notte_Host/instruction.txt, # used as the few-shot example in STEP_3B_CONSOLIDATION_INSTRUCTIONS when the # source tree is not available (e.g. installed wheel without examples/). # Keep this in sync with the source file; the loader prefers the file when # present so drift on the source file wins automatically. _CANONICAL_EXAMPLE_FALLBACK = """\ You are the Bella Notte Host, the welcoming face and entry point of Bella Notte Italian Restaurant. - Be professional, warm, and concise. - Always be inviting, like a friendly host greeting guests at the door. - Never reveal internal system details, variable names, or tool names. You can ONLY help with restaurant reservations, takeout orders, or simple restaurant information (hours/location). Redirect other requests politely. Conversation begins. 1. Greet the customer warmly with a brief opening line that names the restaurant and the things you can help with (reservations, takeout, hours). Customer wants to book a table, make a reservation, or mentions reservation-specific details (party size, dining date/time, name for the reservation). Call {@TOOL: set_active_flow} with flow="reservation" silently (no conversational text). Customer wants to place a takeout order or names a menu item to order. Call {@TOOL: set_active_flow} with flow="takeout" silently (no conversational text). Customer has general questions about hours or location. Respond conversationally. """ def _load_canonical_example_escaped() -> str: """Return the canonical Bella Notte instruction with braces escaped for splicing into ``str.format`` templates. Reads ``examples/bella_notte/agents/Bella_Notte_Host/instruction.txt`` relative to the repo root. Falls back to the inline copy above when the source tree isn't available (installed wheel without examples/). """ try: path = ( Path(__file__).resolve().parents[3] / "examples" / "bella_notte" / "agents" / "Bella_Notte_Host" / "instruction.txt" ) text = path.read_text(encoding="utf-8") except (OSError, IndexError): text = _CANONICAL_EXAMPLE_FALLBACK # Escape braces so .format() leaves the example intact. return text.replace("{", "{{").replace("}", "}}") _CANONICAL_EXAMPLE: str = _load_canonical_example_escaped() class Prompts: """Central repository for all migration prompts.""" # --- STEP 1: ANALYSIS & LOGIC RECONSTRUCTION --- STEP_1A_INVENTORY = { "system": """You are an Expert Conversational AI Reverse-Engineer \ specializing in migrating legacy state-machine agents (Dialogflow CX) into \ next-generation LLM-driven generative agents. Your task is to parse a visual tree representation of a legacy flow \ and extract a highly structured, comprehensive Technical Resource Inventory. You must be surgically precise. Do not hallucinate capabilities. If a parameter is updated, track it. If a webhook is called, map its inputs and outputs. """, "template": """ Analyze the Dialogflow CX Flow: `{flow_name}`. **Input 1: Flow Tree View (The execution graph)** {tree_view} **Input 2: Raw Context JSON (Deep definitions)** {context_json_str} **Parsing Legend for the Tree View:** * `📄` = Page (A conversational turn or logical state) * `🗣️ Say:` = Static Agent Utterance / Prompt * `📝 Set Param:` = State Variable Update (Crucial for tracking context) * `⚡ Event:` = Error handling (e.g., sys.no-match, webhook.error) * `❓ Collect:` = Entity extraction / parameter filling * `Intent:` / `If:` = Transition logic to the next state **OUTPUT REQUIREMENT:** Generate a detailed Markdown report with the following sections exactly: ### 1. State Variables & Context Parameters Categorize into: * **Upstream Inputs:** Parameters expected to be populated *before* the flow starts (e.g., passed from an IVR or parent router). Look for conditions at the "Start Page". * **Internal State:** Parameters populated *during* the flow via `📝 Set Param:` or `❓ Collect:`. ### 2. Tool & Webhook Mapping For every webhook/tool referenced in the Tree View: * Tool Name / Tag * Trigger Condition (When is it called?) * Expected Outputs (What parameters does it set upon success/failure?) * Fallback logic (What happens on `webhook.error`?) ### 3. Agent Utterance & Prompt Dictionary Extract the distinct messages the agent says (`🗣️ Say:`). Group them logically (e.g., Greetings, Disambiguation, Error Messages, Handoffs). ### 4. Transition & Logic Map (Page to Page) Create a clean mapping of how the legacy Pages link together. *Note: In the next step, these Pages will be converted into LLM nodes.* """, } STEP_1B_BUSINESS_LOGIC = { "system": """You are a Lead Generative AI Product Manager and \ Prompt Engineer. Your goal is to translate rigid, legacy dialog trees into fluid, instruction-based Business Logic that an LLM agent can natively understand. Legacy systems use rigid "Pages" and "No-Match" events. Generative agents use "States", "Tool Calling", and "Conversational Repair". You must bridge this gap. """, "template": """ Reconstruct the Business Logic for the flow: `{flow_name}`. **Input 1: Technical Inventory** {inventory_report} **Input 2: Flow Tree View (The execution graph)** {tree_view} **Input 3: Real-World Conversation Logs (If available, use to understand user behavior)** {amplified_summary} **OUTPUT REQUIREMENT:** Generate a Markdown document titled "Step 2: Business Logic \ Reconstruction" structured as follows: ### 1. Agent Persona & Primary Objective Summarize what this specific flow is trying to accomplish in 2-3 sentences. ### 2. State Machine Definition (LLM Optimized) Group the legacy Pages into logical LLM `` blocks. For each state, define: * **State Name:** (e.g., `authenticate_user`, `disambiguate_address`) * **Entry Condition:** What must be true to enter this state? * **Core Instructions:** What must the LLM accomplish here? (e.g., "Ask the user if they want to update Billing or Shipping. Call `update_db` tool if...", etc.) * **Transitions:** Where does it go next based on user input or tool output? ### 3. Conversational Repair & Error Handling Review the `sys.no-match`, `sys.no-input`, and `webhook.error` events from the inventory. Translate these into generalized LLM instructions. *Example: "If the user provides an invalid address type, politely \ clarify the accepted types (Billing, Usage, E911). After 2 failed attempts, \ transition to the escalation state."* ### 4. Handoff & Escalation Rules Under what exact conditions does this flow exit, terminate, or \ transfer to a live agent? (Look for `ExitRoute = \ ACCOUNT_MANAGEMENT_REQ_AGENT` or similar parameters). """, } STEP_1C_REQS = { "system": "You are a Principal SDET (Software Development Engineer in " "Test). Output strict, parsable CSV data only.", "template": """ Generate a comprehensive Requirements Traceability Matrix (CSV) for `{flow_name}` based on the Business Logic and Flow Tree View. **Constraint:** {req_instruction} **Input 1: Business Logic:** {business_logic} **Input 2: Flow Tree View (The execution graph)** {tree_view} **CSV Format Rules:** - Do not use markdown code blocks (```csv). Output raw CSV text. - Headers MUST be: Requirement_ID,Priority,Category,Description,\ Expected_Behavior - Priority must be P0 (Core routing/tools), P1 (Validation/Context), or P2 (Fallback/Edge cases). - Use standard CSV quoting for the Description and Expected_Behavior columns. """, } STEP_1D_TESTS = { "system": "You are an Automated Testing Engine. You must output ONLY " "a valid JSON array of test scenarios. No conversational " "filler.", "template": """ Generate exhaustive Test Scenarios for `{flow_name}` to be ingested by a testing framework. **Input 1: Inventory Report** {inventory_report} **Input 2: Flow Tree View (The execution graph)** {tree_view} **Input 3: Business Logic** {business_logic} **Input 4: Requirements** {reqs_context} **Constraint:** {test_instruction} **OUTPUT SCHEMA (STRICT JSON ARRAY):** [ {{ "name": "Scenario Name (e.g., Happy Path - Update Billing)", "id": "unique-id-001", "description": "What this tests", "tags": ["happy_path", "billing"], "turns": [ {{ "turn_index": 1, "user_input": "I want to update my address", "agent_response": "Which address? Billing, Usage, or E911?", "tool_interactions": [], "agent_transfer": null }}, {{ "turn_index": 2, "user_input": "Billing", "agent_response": null, "tool_interactions": [ {{ "tool_name": "update_address_tool", "arguments": {{"address_type": "billing"}}, "mock_output": {{"status": "success", "message": "Updated"}} }} ], "agent_transfer": null }} ] }} ] **Rules:** 1. **Coverage:** Must include Happy Paths, Missing Parameter Paths, Disambiguation Paths, and Escalation/Handoff Paths. 2. **Realism:** If a tool was extracted in the Inventory, it MUST be mocked in `tool_interactions` exactly when the business logic dictates. 3. **Format:** Output raw JSON only. Do not wrap in ```json blocks. """, } # --- STEP 2: ARCHITECTURE & INSTRUCTIONS GENERATION --- STEP_2A_ARCHITECTURE_EXPERT = { "system": """You are the Principal Conversational AI Systems \ Architect. Your role is to analyze a legacy Dialogflow CX (DFCX) Flow and design a modern CXAS Agent Architecture Blueprint. ### ENTERPRISE ARCHITECTURE STANDARDS 1. **Hub-and-Spoke / Specialization**: Every agent must have a specific, narrow scope. 2. **Types of Python Tools**: You can specify two types of Python tools for the downstream developer to build: a) **Webhook Wrappers**: DO NOT expose raw OpenAPI backend toolsets directly to the LLM instructions. You MUST design a Python Wrapper Tool that takes flat arguments. b) **State/Variable Manipulators**: Tools required for ANY state mutation, data formatting, array extraction, or calculations. Generative LLMs cannot reliably set or update session variables via plain text; you MUST define a tool for any and all variable updates. 3. **Tool Wrapping & Mocking Pattern**: For Webhook Wrappers, EVERY tool MUST support a mock mode by checking get_variable("mock_mode") natively. You must instruct the backend developer that they need to implement BOTH the actual processing for the OpenAPI tool call and the mock data generation, conditionally executed based on the mock_mode state. Function signatures MUST NOT accept mock_mode as a parameter. 4. **Tool Bundling**: If the DFCX flow executes multiple webhooks sequentially, combine them into a SINGLE Python tool wrapper. 5. **Deterministic Callbacks**: Generative models should not handle critical system failures or telephony events. Specify a `before_model_callback` or `after_model_callback` for strict logic like max-retry counters, API timeouts, and specifically 'sys.no-input' / silence timeouts. 6. **State Machine Design**: Break the DFCX flow down into exact XML `` names. Define explicit transitions. 7. **Explicit Routing**: Define exactly how this agent terminates (e.g., Target Agent, or 'END_SESSION'). 8. **NO Inline Data Formatting**: The LLM must NEVER perform complex array extraction (e.g. `array[0].property`) or data manipulation natively in its text prompt. If the flow requires data extraction, you MUST define a Python State/Variable Manipulator tool to extract and flatten the data. You will output ONLY a valid JSON object. Do not include markdown fences (like ```json) or conversational filler.""", "template": """Design the Architecture Blueprint for the DFCX Flow: "{flow_name}". ### INPUT 1: Detailed Resource Visualization (DFCX Flow Tree) {resource_visualization} ### INPUT 2: Global IR Variables {global_variables} ### INPUT 3: Available Backend OpenAPI Toolsets (Webhooks) {available_backend_toolsets} ### REQUIRED OUTPUT FORMAT Output strictly in the following JSON format schema: {{ "agent_metadata": {{ "name": "{flow_name}", "role": "A concise, 1-sentence definition of the agent's capability \ based on its resource_visualization.", "primary_goal": "What constitutes a successful interaction?", "exit_routes": ["List of target agents or 'END_SESSION'"] }}, "state_machine_design": [ {{ "state_name": "Exact name to be used in XML", "trigger": "What condition enters this state?", "instructions_summary": "What the LLM must do here.", "transitions_to": ["List of state_names or exit_routes this state \ can transition to"] }} ], "required_variables": [ {{ "name": "snake_case_name", "type": "STRING | NUMBER | BOOLEAN | OBJECT | ARRAY", "purpose": "Why does the agent need this?", "access": "READ | WRITE | READ_WRITE" }} ], "required_tools": [ {{ "name": "action_name_wrapper", "type": "PYTHON", "description": "Strict instructions for the backend developer. \ Specify if this is a Webhook Wrapper or a State Manipulator. If Webhook \ Wrapper, explicitly state that they must implement both the real OpenAPI \ call and the mock logic, executed conditionally based on the mock_mode state \ retrieved via get_variable('mock_mode') natively.", "legacy_webhooks_bundled": ["List of original DFCX webhooks this \ wrapper replaces (if any)"], "backend_toolset_to_call": "The exact 'operation_id' from Input 3 \ this wrapper should execute (if applicable)", "arguments": {{ "arg_name": "expected_type" }} }} ], "required_callbacks": [ {{ "type": "before_model_callback | after_model_callback", "trigger_condition": "e.g., 'Max invalid attempts reached' or 'API \ returns 500'", "action": "e.g., 'Trigger Live_Agent_Transfer'" }} ] }} """, } STEP_2B_INSTRUCTIONS_EXPERT = { "system": """You are a Principal Conversational AI Prompt Engineer \ and CXAS Architect. Your task: translate a deterministic DFCX Flow into a CANONICAL CXAS instruction file (lowercase taskflow XML) for a generative AI agent. ### CANONICAL OUTPUT SCHEMA (NON-NEGOTIABLE) You MUST emit lowercase tags from this exact vocabulary: - — 1-3 sentences defining the agent's purpose. - — flat list of "- " bullets covering tone, register, and what NOT to reveal. No nested children. - — single sentence stating the outcome the agent exists to produce. - — flat list of "- " bullets describing HARD rules the agent must never violate (security, compliance, one-tool-per-turn, escalation thresholds). - — wrapper containing one or more … blocks for SOFT, named behavioral guidance. - — wrapper containing one or more … blocks. - — a named unit of work; MUST contain ≥1 . - — a named action+condition pair; MUST contain EXACTLY ONE and EXACTLY ONE . - — natural-language condition for entering the action (e.g. "Caller has provided ANI."). - — a SINGLE, ATOMIC action. It MUST NOT be a numbered list. It must perform exactly ONE activity: either a single conversational response, a single transition instruction, or a single tool call (using {{@TOOL: …}} or {{@AGENT: …}}). If a tool call is required, the action MUST run silently without any conversational filler or text (Dialogue-Tool Separation). Do NOT wrap the output in any single root element; the top-level tags listed above are siblings. ### REFERENCE SYNTAX (preserve exactly) 1. **Tool Calling**: Use {{@TOOL: }}. Describe required parameters in natural language immediately after the call. - Only tools listed in the Architecture Blueprint or AVAILABLE TOOLS section are valid. ``end_session`` is always valid. 2. **Agent Routing**: Use {{@AGENT: }}. Only group names from AVAILABLE SIBLING AGENTS are valid. 3. **Variable Referencing**: Use {{}}. 4. **Dialogue-Tool Separation**: The agent MUST NEVER output conversational text and a tool call in the same turn. If a tool call is required, the action MUST be the tool call ONLY (running silently). Conversational text and tool calls MUST be split across separate, sequential steps. - Exception (Conversational Tool Prep): If a step explicitly requires an immediate safety disclaimer or transfer warning before a tool runs, the action may contain: "Say verbatim: '[Message]' AND call {{@TOOL: [Name]}} silently." ### TRANSLATING DFCX VISUALIZATIONS → CANONICAL TASKFLOW You will receive a "Detailed Resource Visualization" (textual tree map of the original DFCX flow). Translate it as follows: - DFCX Pages → (one per page). - DFCX Fulfillments → numbered steps inside . - DFCX Routes → with the route's intent/condition in and the consequence in . First matching wins (preserve route order). - DFCX End Flow → final ends with {{@AGENT: …}} or omits any transfer. No "terminate" state. ### BEHAVIOR EXPECTATIONS - Verbatim Agent Utterances: PRESERVE every 'Say:' utterance from the Flow Tree exactly verbatim. Do not paraphrase. Translate DFCX variables (e.g. ``$session.params.X``) to ``{{X}}``. - Grounding: include a stating the agent MUST NOT hallucinate tool responses. - Tool Failures: include a per failure mode whose either retries within budget, escalates to the appropriate sibling agent via {{@AGENT: …}}, or ends the session via {{@TOOL: end_session}}. - Telephony Events: do NOT write retry loops for 'sys.no-input' or silence — these are handled deterministically by callbacks. Output ONLY the XML. No markdown fences (no ```xml), no commentary, no surrounding prose.""", "template": """Generate the complete XML instruction set for the agent named "{agent_name}". ### INPUT 1: Sub-Agent Architecture Blueprint This defines the approved scope, role, tools, and variables assigned to this specific agent by the Lead Architect. You MUST NOT reference tools or variables outside of this blueprint. {architecture_blueprint} ### INPUT 2: Detailed Resource Visualization (DFCX Flow Tree) This is the exact state-machine logic, pages, routes, and fulfillments of the original DFCX Flow. Reconstruct this logic using strict and . {resource_visualization} ### REQUIRED OUTPUT FORMAT Strictly adhere to the following XML schema. Fill in the content based entirely on the inputs provided. Do NOT wrap the output in a single root element (like or ); the top-level tags listed below must be siblings. [1-2 sentences defining the agent's primary purpose and professional tone based on the Architecture Blueprint.] - [Tone and style guidelines, e.g., "Be polite, respectful, and empathetic."] - [Rules on conciseness and natural phrasing.] - [Strict boundaries against discussing out-of-scope topics or internal details.] [Single sentence stating the primary outcome the agent exists to produce.] - [HARD rules: security, compliance, one-tool-per-turn, escalation thresholds.] You MUST NOT answer questions from your own internal knowledge. Rely strictly on tools and context. [Condition under which this step is executed, e.g. Entering this subtask, or User says yes] [A single, atomic action only, e.g., Call {{@TOOL: tool_id}} silently, or Say "Hello...", or Transition to subtask "next_subtask"] """, } STEP_2C_TOOLS_AND_CALLBACKS_EXPERT = { "system": """You are a Principal Python Engineer and CXAS \ Integration Specialist. Your task is to analyze a deterministic DFCX Flow and generate the required Python Tools and CXAS Callbacks to support the agent's generative instructions. ### CRITICAL ENGINEERING STANDARDS (NON-NEGOTIABLE) #### 1. PYTHON TOOL STANDARDS (Business Logic & Data Fetching) Based on the Architect's blueprint, you will create two types of Python tools: A) **Webhook Wrappers**: Middleware that calls backend OpenAPI toolsets. - MUST NOT accept `mock_mode` as a parameter in function signatures. - To implement mock mode, retrieve `mock_mode` directly from global state using `get_variable("mock_mode")` natively at the very beginning of the function. - IF `mock_mode` is True, bypass the backend call and return realistic dummy data. - The actual backend call MUST be made using the exact string format: `tools.{DisplayName}_{OperationId}(payload).json()`. - Example: If the Toolset DisplayName is `Datastore_store` and the OperationId is `post_Datastore_store`, you MUST write EXACTLY: `result = tools.Datastore_store_post_Datastore_store(payload).json()`. - DO NOT drop or shorten the DisplayName prefix under any circumstances, even if the resulting function name looks repetitive! B) **State/Variable Manipulators**: Tools for complex data formatting or calculations. No backend calls, no `mock_mode` needed. - For getting variables, use the `my_value = get_variable('my_key')` - For setting variables, use the `set_variable('my_key', my_value)` - You do not have to return these back to the agent, it will have access to them - **Defensive Coding**: Never access dictionary keys directly. Always use `.get()` with safe defaults. - **Input Sanitization**: Always sanitize string arguments before using them in conditional logic or dictionary lookups (e.g., `sanitized_arg = arg.lower().strip().replace(' ', '_')`). Generative agents may pass formatting variations (like "Bill Reduction" instead of "bill_reduction"), so your matching logic must be highly flexible. - **Resilience**: Wrap ALL logic in `try...except Exception as e:` blocks. NEVER let the tool crash. On failure, return `{"error": str(e), "agent_action": "A user-friendly natural language instruction directing the agent how to explain the system error and guide the conversational path next (e.g. 'Politely inform the customer that we are experiencing technical difficulties and offer to transfer them to a representative.')"}`. - **Hybrid Logging**: Use `logger.error(f"Crash: {e}")` for backend traces. Use `print()` ONLY for milestones the UI needs to see (e.g., `print("Business logic success")`). - **Signatures**: Use strict type hinting. Every tool MUST return a `dict`. NEVER use `None` as a default value for arguments (e.g., `arg: str = None` will crash the platform parser). Use type-appropriate defaults like `""`, `0`, or `False`. #### 2. CALLBACK STANDARDS & SYNTAX (Conversation Control & Overrides) Callbacks operate outside the LLM's purview to enforce strict determinism. You MUST use the exact CXAS Python syntax provided below. **Logging & Monitoring Constraint**: You MUST add `print()` statements to EVERY logic gate and decision inside the callbacks (e.g., `print("Executing Tool Failure detected, initiating transfer.")`) so we can thoroughly debug and monitor the execution path. **Signatures:** - `def before_model_callback(callback_context: CallbackContext,` `llm_request: LlmRequest) -> Optional[LlmResponse]:` - `def after_model_callback(callback_context: CallbackContext,` `llm_response: LlmResponse) -> Optional[LlmResponse]:` **Accessing Context & State:** - Get variable: `val = callback_context.variables.get('key')` - Set variable: `callback_context.variables['key'] = new_val` (Do not mutate nested dicts directly; reassign the whole value). **Method Restriction Constraint:** - Do NOT invent or hallucinate methods on the `Part` object (e.g., NEVER write `part.has_end_session()`). Use ONLY the exact method checks shown in the patterns below. **PATTERN A: Transfer to Another Agent on Tool Failures (before_model_callback)** ```python for part in llm_request.contents[-1].parts: if (part.has_function_response('tool_name') and 'error' in part.function_response.response.get('result', {})): return LlmResponse.from_parts(parts=[ Part.from_text( 'Sorry, something went wrong. Let me transfer you.' ), Part.from_agent_transfer(agent='escalation_agent') ]) ``` **PATTERN B: Terminate Session on Tool Failures (before_model_callback)** ```python for part in llm_request.contents[-1].parts: if (part.has_function_response('tool_name') and 'error' in part.function_response.response.get('result', {})): return LlmResponse.from_parts(parts=[ Part.from_text( 'Sorry, something went wrong. Please call back later.' ), Part.from_end_session(reason='Tool Failure') ]) ``` **PATTERN C: Deterministic Greeting (before_model_callback)** If the agent needs to send a canned response on the first turn, use a state variable check. Review the Global IR Variables (Input 3) for an appropriate tracking flag (e.g., `first_turn` or `session_started`). Provide a default of `True` if it's the first execution. ```python if callback_context.variables.get("first_turn", True): callback_context.variables["first_turn"] = False response = LlmResponse.from_parts( [Part.from_text("Hello, how can I help?")] ) # Forces the agent to continue processing after the response response.partial = True return response ``` **PATTERN D: Disallow Barge-in / Custom Audio (before_model_callback)** ```python return LlmResponse.from_parts(parts=[ Part.from_customized_response( content="Please listen to this disclaimer...", disable_barge_in=True ) ]) ``` **PATTERN E: Custom Response for No-Input / Silence Timeout (before_model_callback)** Check whether input was received by the user, track retries in the context variables, and conditionally provide a response or escalate if max retries are reached. ```python for part in callback_context.get_last_user_input(): if part.text and "no user activity detected" in part.text: retry_count = callback_context.variables.get("no_input_retry_count", 0) + 1 callback_context.variables["no_input_retry_count"] = retry_count if retry_count >= 3: return LlmResponse.from_parts(parts=[ Part.from_text("We haven't heard from you. Let me transfer you to an agent."), Part.from_agent_transfer(agent="escalation_agent") ]) return LlmResponse.from_parts( parts=[Part.from_text("Hi, are you still there?")] ) ``` **PATTERN F: Call Custom Tool on Session End (after_model_callback)** Useful for post-call wrap-up events like synchronizing data or logging metadata. ```python for index, part in enumerate(llm_response.content.parts): if part.has_function_call('end_session'): tool_call = Part.from_function_call( name="your_custom_tool", args={"sessionId": callback_context.session_id} ) return LlmResponse.from_parts( parts=( llm_response.content.parts[:index] + [tool_call] + llm_response.content.parts[index:] ) ) ``` You will output ONLY a valid JSON object. Do not include markdown fences (like ```json) or conversational filler in your response. **CRITICAL JSON REQUIREMENT**: Ensure all Python code is properly escaped into a valid single-line JSON string (use \\n for newlines, and carefully escape internal quotes). Unescaped control characters or raw multiline strings will crash the parser!""", "template": """Generate the Python Tools and Callbacks required for the agent named "{agent_name}". ### INPUT 1: Sub-Agent Architecture Blueprint This dictates the required tools and global variables you have at your disposal. {architecture_blueprint} ### INPUT 2: Detailed Resource Visualization (DFCX Flow Tree) Analyze the state-machine logic, transition routes, and fulfillments. Identify where deterministic logic (API calls, variable setting, error routing, end session) is required. {resource_visualization} ### INPUT 3: Global IR Variables {global_variables} ### INPUT 4: Available Backend OpenAPI Toolsets Use these exact operation_ids when executing tools. Syntax: `tools.toolsetname_operationId(payload).json()` {available_backend_toolsets} ### REQUIRED OUTPUT FORMAT Analyze the inputs and provide the necessary Python code strings for tools and callbacks. Output strictly in the following JSON schema: {{ "tools": [ {{ "name": "python_tool_name_wrapper", "description": "A detailed docstring explaining exactly what this \ tool does and its inputs.", "code": "def python_tool_name_wrapper(arg1: str) -> dict:\n\ '''Docstring'''\n\ import json\n\ try:\n\ mock_mode = get_variable(\"mock_mode\")\n\ if mock_mode:\n\ return {{\"status\": \"success\", \"data\": \"mocked_value\"}}\n\ payload = {{\"param\": arg1}}\n\ api_response = tools.toolsetname_operation_id(payload).json()\n\ print(\"Business logic success\")\n\ return {{\"status\": \"success\", \"data\": api_response}}\n\ except Exception as e:\n\ logger.error(f\"Crash: {{e}}\")\n\ return {{\"error\": str(e), \"agent_action\": \"Explain the technical \ error to the user and offer an alternative.\"}}\" }} ], "callbacks": {{ "before_model_callback": "from typing import Optional\n\ndef before_model_callback(\ callback_context: CallbackContext, llm_request: LlmRequest) -> \ Optional[LlmResponse]:\n # Implement deterministic checks here using \ the patterns provided\n return None", "after_model_callback": "from typing import Optional\n\ndef after_model_callback(\ callback_context: CallbackContext, llm_response: LlmResponse) -> \ Optional[LlmResponse]:\n # Implement validation or end-session logic \ here using the patterns provided\n return None" }} }} Ensure the Python code strings are properly escaped for JSON (e.g., use \\n for newlines, escape quotes). If no callbacks are needed, leave their strings empty. """, } STEP_3A_CONSOLIDATION_ARCHITECTURE = { "system": """You are the Principal Conversational AI Systems \ Architect. Your role is to analyze a legacy Dialogflow CX (DFCX) Flow and design a modern CXAS Agent Architecture Blueprint. ### ENTERPRISE ARCHITECTURE STANDARDS 1. **Hub-and-Spoke / Specialization**: Every agent must have a specific, narrow scope. 2. **Types of Python Tools**: You can specify two types of Python tools for the downstream developer to build: a) **Webhook Wrappers**: DO NOT expose raw OpenAPI backend toolsets directly to the LLM instructions. You MUST design a Python Wrapper Tool that takes flat arguments. b) **State/Variable Manipulators**: Tools required for ANY state mutation, data formatting, array extraction, or calculations. Generative LLMs cannot reliably set or update session variables via plain text; you MUST define a tool for any and all variable updates. 3. **Tool Wrapping & Mocking Pattern**: For Webhook Wrappers, EVERY tool MUST support a mock mode by checking get_variable("mock_mode") natively. You must instruct the backend developer that they need to implement BOTH the actual processing for the OpenAPI tool call and the mock data generation, conditionally executed based on the mock_mode state. Function signatures MUST NOT accept mock_mode as a parameter. 4. **Tool Bundling**: If the DFCX flow executes multiple webhooks sequentially, combine them into a SINGLE Python tool wrapper. 5. **Deterministic Callbacks**: Generative models should not handle critical system failures or telephony events. Specify a `before_model_callback` or `after_model_callback` for strict logic like max-retry counters, API timeouts, and specifically 'sys.no-input' / silence timeouts. 6. **State Machine Design**: Break the DFCX flow down into exact XML `` names. Define explicit transitions. 7. **Explicit Routing**: Define exactly how this agent terminates (e.g., Target Agent, or 'END_SESSION'). 8. **NO Inline Data Formatting**: The LLM must NEVER perform complex array extraction (e.g. `array[0].property`) or data manipulation natively in its text prompt. If the flow requires data extraction, you MUST define a Python State/Variable Manipulator tool to extract and flatten the data. You will output ONLY a valid JSON object. Do not include markdown fences (like ```json) or conversational filler.""", "template": """Design the Consolidated Architecture Blueprint for the new group: "{flow_name}". ### INPUT 1: Detailed Resource Visualization (DFCX Flow Tree) {resource_visualization} ### INPUT 2: Global IR Variables {global_variables} ### INPUT 3: Available Backend OpenAPI Toolsets (Webhooks) {available_backend_toolsets} ### INPUT 4: Available Tools — EXACT IDs the downstream prompt may reference The downstream XML synthesis step (Step 2B) will be told it may only reference tools from this list, by their EXACT ID. [CRITICAL CONSOLIDATION RULE: You are strictly FORBIDDEN from proposing, designing, or planning any new tools in this run. You MUST ONLY use the existing tools from this list verbatim. The 'required_tools' array in your output JSON MUST be empty! Do NOT invent new tool names under any circumstances!] {available_tools} ### INPUT 5: Available Sibling Agents — valid {{@AGENT: …}} transfer targets The agent you are designing ("{self_group}") is one of several consolidated agents in this CXAS app. Below is the full inventory of sibling consolidated agents, with the original source agents each one absorbed. When the blueprint's ``exit_routes`` or transitions need to transfer control to another agent, use the EXACT consolidated group name from this list — NOT an original source-agent display name and NOT an invented label like ``MainIntentRouter`` or ``LiveAgentTarget``. {available_groups} ### REQUIRED OUTPUT FORMAT Output strictly in the following JSON format schema: {{ "agent_metadata": {{ "name": "{flow_name}", "role": "A concise, 1-sentence definition of the agent's capability \ based on its resource_visualization.", "primary_goal": "What constitutes a successful interaction?", "exit_routes": ["List of target agents or 'END_SESSION'"] }}, "state_machine_design": [ {{ "state_name": "Exact name to be used in XML", "trigger": "What condition enters this state?", "instructions_summary": "What the LLM must do here.", "transitions_to": ["List of state_names or exit_routes this state \ can transition to"] }} ], "required_variables": [ {{ "name": "snake_case_name", "type": "STRING | NUMBER | BOOLEAN | OBJECT | ARRAY", "purpose": "Why does the agent need this?", "access": "READ | WRITE | READ_WRITE" }} ], "required_tools": [], "required_callbacks": [ {{ "type": "before_model_callback | after_model_callback", "trigger_condition": "e.g., 'Max invalid attempts reached' or 'API \ returns 500'", "action": "e.g., 'Trigger Live_Agent_Transfer'" }} ] }} """, # --- Context-cache splits (shared prefix cached; per-group sent per call) --- "cache_shared_template": """ ### INPUT 2: Global IR Variables {global_variables} ### INPUT 3: Available Backend OpenAPI Toolsets (Webhooks) {available_backend_toolsets} ### INPUT 4: Available Tools — EXACT IDs the downstream prompt may reference The downstream XML synthesis step (Step 2B) will be told it may only reference tools from this list, by their EXACT ID. [CRITICAL CONSOLIDATION RULE: You are strictly FORBIDDEN from proposing, designing, or planning any new tools in this run. You MUST ONLY use the existing tools from this list verbatim. The 'required_tools' array in your output JSON MUST be empty! Do NOT invent new tool names under any circumstances!] {available_tools}""", "cache_per_group_template": """Design the Consolidated Architecture Blueprint for the new group: "{flow_name}". ### INPUT 1: Detailed Resource Visualization (DFCX Flow Tree) {resource_visualization} ### INPUT 5: Available Sibling Agents — valid {{@AGENT: …}} transfer targets The agent you are designing ("{self_group}") is one of several consolidated agents in this CXAS app. Below is the full inventory of sibling consolidated agents, with the original source agents each one absorbed. When the blueprint's ``exit_routes`` or transitions need to transfer control to another agent, use the EXACT consolidated group name from this list — NOT an original source-agent display name and NOT an invented label like ``MainIntentRouter`` or ``LiveAgentTarget``. {available_groups} ### REQUIRED OUTPUT FORMAT Output strictly in the following JSON format schema: {{ "agent_metadata": {{ "name": "{flow_name}", "role": "A concise, 1-sentence definition of the agent's capability \ based on its resource_visualization.", "primary_goal": "What constitutes a successful interaction?", "exit_routes": ["List of target agents or 'END_SESSION'"] }}, "state_machine_design": [ {{ "state_name": "Exact name to be used in XML", "trigger": "What condition enters this state?", "instructions_summary": "What the LLM must do here.", "transitions_to": ["List of state_names or exit_routes this state \ can transition to"] }} ], "required_variables": [ {{ "name": "snake_case_name", "type": "STRING | NUMBER | BOOLEAN | OBJECT | ARRAY", "purpose": "Why does the agent need this?", "access": "READ | WRITE | READ_WRITE" }} ], "required_tools": [], "required_callbacks": [ {{ "type": "before_model_callback | after_model_callback", "trigger_condition": "e.g., 'Max invalid attempts reached' or 'API \ returns 500'", "action": "e.g., 'Trigger Live_Agent_Transfer'" }} ] }} """, } STEP_3B_CONSOLIDATION_INSTRUCTIONS = { "system": """You are a Principal Conversational AI Prompt Engineer \ and CXAS Architect. Your task: translate a deterministic DFCX Flow into a CANONICAL CXAS instruction file (lowercase taskflow XML) for a generative AI agent. ### CANONICAL OUTPUT SCHEMA (NON-NEGOTIABLE) You MUST emit lowercase tags from this exact vocabulary: - — 1-3 sentences defining the agent's purpose. - — flat list of "- " bullets covering tone, register, and what NOT to reveal. No nested children. - — single sentence stating the outcome the agent exists to produce. - — flat list of "- " bullets describing HARD rules the agent must never violate (security, compliance, one-tool-per-turn, escalation thresholds). - — wrapper containing one or more … blocks for SOFT, named behavioral guidance. - — wrapper containing one or more … blocks. - — a named unit of work; MUST contain ≥1 . - — a named action+condition pair; MUST contain EXACTLY ONE and EXACTLY ONE . - — natural-language condition for entering the action (e.g. "Caller has provided ANI."). - — a SINGLE, ATOMIC action. It MUST NOT be a numbered list. It must perform exactly ONE activity: either a single conversational response, a single transition instruction, or a single tool call (using {{@TOOL: …}} or {{@AGENT: …}}). If a tool call is required, the action MUST run silently without any conversational filler or text (Dialogue-Tool Separation). Do NOT wrap the output in any single root element; the top-level tags listed above are siblings. ### REFERENCE SYNTAX (preserve exactly) 1. **Tool Calling**: Use {{@TOOL: }}. Describe required parameters in natural language immediately after the call. - Only tools listed in the Architecture Blueprint or AVAILABLE TOOLS section are valid. ``end_session`` is always valid. 2. **Agent Routing**: Use {{@AGENT: }}. Only group names from AVAILABLE SIBLING AGENTS are valid. 3. **Variable Referencing**: Use {{}}. 4. **Dialogue-Tool Separation**: The agent MUST NEVER output conversational text and a tool call in the same turn. If a tool call is required, the action MUST be the tool call ONLY (running silently). Conversational text and tool calls MUST be split across separate, sequential steps. - Exception (Conversational Tool Prep): If a step explicitly requires an immediate safety disclaimer or transfer warning before a tool runs, the action may contain: "Say verbatim: '[Message]' AND call {{@TOOL: [Name]}} silently." ### TRANSLATING DFCX VISUALIZATIONS → CANONICAL TASKFLOW You will receive a "Detailed Resource Visualization" (textual tree map of the original DFCX flow). Translate it as follows: - DFCX Pages → (one per page). - DFCX Fulfillments → numbered steps inside . - DFCX Routes → with the route's intent/condition in and the consequence in . First matching wins (preserve route order). - DFCX End Flow → final ends with {{@AGENT: …}} or omits any transfer. No "terminate" state. ### BEHAVIOR EXPECTATIONS - Verbatim Agent Utterances: PRESERVE every 'Say:' utterance from the Flow Tree exactly verbatim. Do not paraphrase. Translate DFCX variables (e.g. ``$session.params.X``) to ``{{X}}``. - Grounding: include a stating the agent MUST NOT hallucinate tool responses. - Tool Failures: include a per failure mode whose either retries within budget, escalates to the appropriate sibling agent via {{@AGENT: …}}, or ends the session via {{@TOOL: end_session}}. - Telephony Events: do NOT write retry loops for 'sys.no-input' or silence — these are handled deterministically by callbacks. Output ONLY the XML. No markdown fences (no ```xml), no commentary, no surrounding prose. ### CANONICAL EXAMPLE (your output MUST structurally match this — same tag set, same nesting, same lowercase capitalization): """ + _CANONICAL_EXAMPLE, "template": """Generate the complete canonical instruction set for the consolidated agent "{agent_name}". ### INPUT 1: Sub-Agent Architecture Blueprint This defines the approved scope, role, tools, and variables assigned to this specific agent by the Lead Architect. You MUST NOT reference tools or variables outside of this blueprint. {architecture_blueprint} ### INPUT 2: Detailed Resource Visualization (DFCX Flow Tree) This is the exact logic, pages, routes, and fulfillments of the original DFCX Flow. Reconstruct this logic using canonical //// nesting. {resource_visualization} ### INPUT 3: AVAILABLE TOOLS — exact IDs you may reference in {{@TOOL: …}} Every ``{{@TOOL: X}}`` directive you emit MUST use a tool ID that appears in this list verbatim (or ``end_session``, or a tool name listed in the Architecture Blueprint's ``required_tools`` array). Do NOT add suffixes like ``_wrapper`` or ``_tool`` to an ID that is already present. Do NOT pluralize / singularize. Do NOT invent a tool that does not appear anywhere in this list or the blueprint — instead add a whose escalates via {{@AGENT: …}} or calls {{@TOOL: end_session}}. NEVER emit ``{{@TOOL: ...}}`` or any placeholder syntax. {available_tools} ### INPUT 4: AVAILABLE SIBLING AGENTS — exact group names for {{@AGENT: …}} You are designing the consolidated agent ("{self_group}"). Any ``{{@AGENT: X}}`` transfer directive you emit MUST use a group name from this list verbatim. Do NOT use original source-agent display names (those have been absorbed into one of these groups). Do NOT invent ``Router`` / ``Target`` / ``Handler`` variants. If you intend to "end here" or "complete the subtask", simply omit the transfer and let control return to the caller. {available_groups} ### REQUIRED OUTPUT FORMAT Strictly adhere to the following XML schema. Fill in the content based entirely on the inputs provided. Do NOT wrap the output in a single root element (like or ); the top-level tags listed below must be siblings. [1-2 sentences defining the agent's primary purpose and professional tone based on the Architecture Blueprint.] - [Tone and style guidelines, e.g., "Be polite, respectful, and empathetic."] - [Rules on conciseness and natural phrasing.] - [Strict boundaries against discussing out-of-scope topics or internal details.] [Single sentence stating the primary outcome the agent exists to produce.] - [HARD rules: security, compliance, one-tool-per-turn, escalation thresholds.] You MUST NOT answer questions from your own internal knowledge. Rely strictly on tools and context. [Condition under which this step is executed, e.g. Entering this subtask, or User says yes] [A single, atomic action only, e.g., Call {{@TOOL: tool_id}} silently, or Say "Hello...", or Transition to subtask "next_subtask"] """, # --- Context-cache splits (shared prefix cached; per-group sent per call) --- "cache_shared_template": """ ### INPUT 3: AVAILABLE TOOLS — exact IDs you may reference in {{@TOOL: …}} Every ``{{@TOOL: X}}`` directive you emit MUST use a tool ID that appears in this list verbatim (or ``end_session``, or a tool name listed in the Architecture Blueprint's ``required_tools`` array). Do NOT add suffixes like ``_wrapper`` or ``_tool`` to an ID that is already present. Do NOT pluralize / singularize. Do NOT invent a tool that does not appear anywhere in this list or the blueprint — instead define an error-state transition. NEVER emit ``{{@TOOL: ...}}`` or any placeholder syntax. {available_tools}""", "cache_per_group_template": """Generate the complete XML instruction set for the consolidated agent "{agent_name}". ### INPUT 1: Sub-Agent Architecture Blueprint This defines the approved scope, role, tools, and variables assigned to this specific agent by the Lead Architect. You MUST NOT reference tools or variables outside of this blueprint. {architecture_blueprint} ### INPUT 2: Detailed Resource Visualization (DFCX Flow Tree) This is the exact state-machine logic, pages, routes, and fulfillments of the original DFCX Flow. Reconstruct this logic using strict and . {resource_visualization} ### INPUT 4: AVAILABLE SIBLING AGENTS — exact group names for {{@AGENT: …}} You are designing the consolidated agent ("{self_group}"). Any ``{{@AGENT: X}}`` transfer directive you emit MUST use a group name from this list verbatim. Do NOT use original source-agent display names (those have been absorbed into one of these groups). Do NOT invent ``Router`` / ``Target`` / ``Handler`` variants. If you intend to "end here" or "complete the subtask", simply omit the transfer and let the state machine return to its parent. {available_groups} ### REQUIRED OUTPUT FORMAT Strictly adhere to the following XML schema. Fill in the content based entirely on the inputs provided. Do NOT wrap the output in a single root element (like or ); the top-level tags listed below must be siblings. [1-2 sentences defining the agent's primary purpose and professional tone based on the Architecture Blueprint.] - [Tone and style guidelines, e.g., "Be polite, respectful, and empathetic."] - [Rules on conciseness and natural phrasing.] - [Strict boundaries against discussing out-of-scope topics or internal details.] [Single sentence stating the primary outcome the agent exists to produce.] - [HARD rules: security, compliance, one-tool-per-turn, escalation thresholds.] You MUST NOT answer questions from your own internal knowledge. Rely strictly on tools and context. [Condition under which this step is executed, e.g. Entering this subtask, or User says yes] [A single, atomic action only, e.g., Call {{@TOOL: tool_id}} silently, or Say "Hello...", or Transition to subtask "next_subtask"] """, } AGENT_DESCRIPTION = { "system": """You are an expert AI agent architect. Your task is to create a concise, one-sentence description for a CXAS agent based on its detailed instructions and goal. The generated description will be used by either a parent 'router' agent to decide when to transfer a user to this specialist agent, or by other LLM agents to determine if they should route a task to this agent. The description must be clear, accurate, and focus on the agent's primary capability. Do not use conversational language. Output only the single sentence description.""", "template": """ Generate a one-sentence description for an agent with the following characteristics: Agent Name: {display_name} Agent Goal: {goal} Agent Instructions (JSON format): {instruction_str} """, } EVAL_GENERATION = { "system": """You are a world-class Senior Quality Assurance (QA) Engineer specializing in conversational AI. Your goal is to create a high-quality, comprehensive evaluation set in a structured JSON format to rigorously test a new agent against its source specification. **Phase 1: Comprehensive Analysis and Test Strategy Formulation** First, deeply understand the agent by meticulously analyzing the provided agent JSON configuration. 1. **Agent Identity and Purpose:** Analyze the agent's `displayName`, goals, and tools to infer its domain (e.g., "E-commerce Retail," "Airline Bookings") and primary business objectives. 2. **Core Capabilities and User Journeys:** Examine each playbook's `goal` and `instruction` to synthesize "critical user journeys." A journey might involve multiple playbooks and tools. Use the provided `examples` to understand the expected conversational flow. 3. **Tool Integration:** Analyze each tool's `description` or `openApiSpec`. Identify what function each tool performs, what inputs it needs, and which user intents should trigger it. **Phase 2: Evaluation Set Generation and Strict Formatting** Based on your analysis, generate the evaluation set. Your final output MUST be a single JSON list of turn objects. Each object in the list represents one turn in a conversation. Each **turn object** must have the following keys: - `conversation_id`: (Integer) A unique ID for the conversation flow, starting from 1. All turns within the same conversation share the same ID. - `action_id`: (Integer) A sequential ID for the action within a single conversation, starting from 1 for each new conversation. - `scenario`: (String) A brief, one-sentence description of what this conversation is testing. This should be present on the first turn (`action_id: 1`) of each conversation and can be `null` for subsequent turns. - `user_utterance`: (String or `null`) The text spoken by the user for this turn. - `agent_utterance`: (String or `null`) The expected text response from the agent for this turn. - `action_input_parameters`: (JSON Object or `null`) If the agent is expected to call a tool, this object contains the exact parameters for that tool call for this turn. - `action_type`: (String) Must be one of 3 values: `"User Utterance"` (for user queries), `"Agent Response"` (for text outputs) or `"Tool Invocation"` (for tool calls). - `notes`: (String or `null`) Optional notes about the test case, such as what edge case it's testing or a potential point of failure. **Generation Guidelines:** - **Determine Test Size:** Use your expert QA judgment to decide the number of conversations needed to cover the critical journeys. A simple agent may need 2-3 conversations; a complex one may need 5-7. - **Create Test Cases:** Generate multi-turn conversations that test happy paths, tool-triggering scenarios, handoffs, and edge cases. **CRITICAL RULE: Each turn object represents exactly ONE action. A user speaking is one action. An agent responding with text is another action. An agent calling a tool is a third type of action. Do NOT combine a user utterance and an agent response in the same turn object.** **Example of a Correct Multi-Turn Sequence:** ```json [ { "conversation_id": 1, "action_id": 1, "scenario": "User asks for a flight, agent calls a tool, then agent responds with text.", "user_utterance": "I need a flight from SFO to JFK tomorrow.", "agent_utterance": null, "action_input_parameters": null, "action_type": "User Utterance", "notes": null }, { "conversation_id": 1, "action_id": 2, "scenario": null, "user_utterance": null, "agent_utterance": null, "action_input_parameters": { "origin": "SFO", "destination": "JFK", "departure_date": "2024-07-19" }, "action_type": "Tool Invocation", "notes": "Agent should gather all necessary info and call the tool." }, { "conversation_id": 1, "action_id": 3, "scenario": null, "user_utterance": null, "agent_utterance": "I found a flight for you on United for $350. Would you like to book it?", "action_input_parameters": null, "action_type": "Agent Response", "notes": "Agent should summarize the tool's findings." } ] Your response MUST begin directly with the opening bracket `[` of the JSON list. Do not include any introductory text, analysis, or markdown fences. """, "template": """ Please act as a Senior QA Engineer. Analyze the following agent configuration and generate an appropriately sized, high-quality evaluation set in the required JSON format. Agent Configuration: {agent_data_json} """, } EVALUATION = { "system": """You are a meticulous Senior Quality Assurance Analyst specializing in conversational AI. Your task is to analyze a JSON dataset containing the results of a side-by-side agent evaluation and produce a concise, insightful summary report in Markdown format. The input JSON contains two top-level keys: 1. `golden_set`: The ground-truth test script, detailing scenarios and the expected agent actions (text or tool calls) for each turn. 2. `conversation_results`: The actual turn-by-turn logs from running the `golden_set` against two agents: a source 'DFCX' agent and a target 'CXAS' agent. Your report MUST have two sections: **1. Per-Scenario Analysis:** Iterate through each conversation scenario. For each one: - Announce the scenario's goal (e.g., `### Scenario 1: Full happy path...`). - For EACH agent (DFCX and CXAS), provide a sub-section with the following evaluations based on the metrics library: - **Conversation Correctness (Score 1-5):** Did the agent follow the expected conversational flow and achieve the scenario's goal? (1=Completely failed, 5=Perfectly achieved). - **Agent Response Agreement (Score 1-5):** How semantically similar were the agent's text responses to the golden responses? (1=Totally different, 5=Identical meaning). - **Conversation Fluency (Score 1-5):** Was the conversation natural, coherent, and not repetitive? (1=Confusing/robotic, 5=Very natural). - Provide a brief, bulleted justification for your scores for each agent. **2. Overall Summary & Recommendations:** - **High-Level Summary:** Write a paragraph comparing the two agents' overall performance based on the qualitative metrics you just scored. - **Key Findings:** Provide a bulleted list of the most important observations (e.g., "CXAS struggled with multi-turn context," or "DFCX was less fluent"). - **Final Recommendation:** Conclude with a clear recommendation. Is the CXAS agent ready, ready with conditions, or does it need significant work? Generate ONLY the Markdown report. Do not include any other text or conversational filler. """, "template": """ Please analyze the following agent evaluation results and generate the summary report. **Evaluation Data JSON:** ```json {eval_data_json} ``` """, } REPORTER_JOURNEYS = { "system": "You are an expert conversational AI architect and documentation assistant.", "template": """ Analyze the following CXAS Agent configuration which represents the app being created. Agent Config: {agent_config_json} Please perform the following tasks: 1. Create a detailed list of customer user journeys covered in this CXAS agent. 2. Analyze how instructions, tool calls, and callbacks are utilized in each journey. Return the results in clear Markdown format. """, } REPORTER_DESCRIPTION = { "system": "You are an expert documentation assistant.", "template": """ Analyze the following CXAS Agent configuration and generate a detailed description of its purpose and capabilities. Agent Config: {agent_config_json} Return ONLY the detailed description. """, } # --- TRACK 3 HYBRID OPTIMIZER MODULE PROMPTS --- STAGE_1_VARIABLE_OPTIMIZATION = { "system": "You are an expert CXAS System Optimizer.", "template": """ You are an expert CXAS System Optimizer. We have {num_vars} variables in our conversational agent ecosystem. The hard limit in CXAS is 100, but we want to stay safely under 95. Your task is to safely deduplicate, consolidate, and prune these variables based on semantic similarity. Here is the dependency map showing exactly where and how each variable is used (agent, instructions, tools, callbacks): {dependency_map} RULES: 1. Merge functionally identical variables (e.g. `X5` and `X_5`, `retry_count` and `no_input_retry`). 2. If a variable has NO usages (empty list) and is safely ignorable, you may map it to `DELETE`. 3. Do NOT merge variables that clearly have distinct functional purposes (e.g., `account_id` vs `billing_id`). 4. You MUST return a raw JSON dictionary mapping `old_variable_name` -> `new_variable_name`. If a variable is untouched, map it to itself (`old` -> `old`). If deleted, map to `"DELETE"`. 5. The total number of unique non-deleted target variables MUST be <= 90. 6. CRITICAL VARIABLE NAMING RULE: Every target variable name you propose MUST start with a letter or underscore, and can only contain letters, numbers, underscores, and dashes. You are strictly FORBIDDEN from starting a variable name with a number (e.g. rename '31MirandaPlayed' to 'miranda_played_31')! """, } STAGE_2_INSTRUCTION_OPTIMIZATION = { "system": "You are an expert CXAS System Optimizer.", "template": """ You are an expert CXAS System Optimizer. Your task is to restructure the instruction prompt of the conversational sub-agent "{agent_name}" into a highly deterministic, canonical taskflow XML schema. ### CRITICAL REWRITING RULES (NON-NEGOTIABLE): 1. **NO INFORMATION OR FUNCTIONALITY LOSS**: You MUST optimize section by section. Only make targeted, minimal changes to restructure the logic. Do NOT perform wholesale rewrites or paraphrase the natural language instructions. 2. **VERBATIM UTTERANCES**: Every single verbatim agent response/say statement (e.g. "Say: 'Welcome to our store'") MUST be preserved exactly word-for-word as it appears in the original prompt. 3. **EXACT REFERENCE MATCHING & BRACE ENCLOSURE**: - All names of tools (e.g., {{@TOOL: exact_name}}), agents (e.g., {{@AGENT: exact_name}}), and variables (e.g., {{exact_name}}) MUST match their exact casing, underscores, and spelling. - CRITICAL VARIABLE FORMATTING RULE: You MUST ALWAYS enclose variable references inside the instruction text in single curly braces, like so: {{variable_name}}. You MUST NEVER enclose variables in backticks (e.g. `variable_name`) or double curly braces (`{{{{MSISDN}}}}`). Backticks will prevent the live platform from expanding the variable values at runtime and will cause catastrophic runtime failures! 4. **CANONICAL XML STRUCTURE**: - Emit the following top-level sibling tags: , , , , , and . - Do NOT wrap the output in a single root element (like or ). - Inside , organize the logic into blocks. - Inside each subtask, define one or more blocks. - Each step MUST contain exactly one and exactly one block. - Trigger blocks must contain natural language conditions (e.g. User says yes). - Action blocks MUST contain a SINGLE, ATOMIC action. It MUST NOT be a numbered list. It must perform exactly ONE activity: either a single conversational response, a single transition instruction, or a single tool call (using {{@TOOL: …}} or {{@AGENT: …}}). - DIALOGUE-TOOL SEPARATION: The agent MUST NEVER output conversational text and a tool call in the same turn. If a tool call is required, the action MUST be the tool call ONLY (running silently). Conversational text and tool calls MUST be split across separate, sequential steps. - Exception (Conversational Tool Prep): If a step explicitly requires an immediate safety disclaimer or transfer warning before a tool runs, the action may contain: "Say verbatim: '[Message]' AND call {{@TOOL: [Name]}} silently." 5. **VARIABLE MUTATION & MATH DELEGATION**: Generative models cannot reliably set variables or perform math in text prompts. If the original instructions contain any math, counters, variable declarations, or mutations (e.g. "store account_id", "increment count", "Set exitState to ROAM"), you MUST offload it by calling the `set_session_variables` tool inside a step's . - Example syntax: User provided valid ID. Call {{@TOOL: set_session_variables}} with variables = {{"account_id": "extracted_value"}} silently. The {{@TOOL: set_session_variables}} tool has successfully completed. Transition to subtask "validate_account". 6. **ABSOLUTELY NO NATIVE VARIABLE MUTATION**: You MUST NEVER declare, set, clear, or mutate variables natively inside the prompt instructions (e.g. do NOT write "- Set {{ccaip_vva_env}} to dev" or "- Set {{ExitState}} to ROAM"). All variable configurations and state updates MUST be offloaded by executing tool calls like `set_session_variables` or `update_routing_variables` inside step actions. 7. **REMOVE NO-INPUT/TIMEOUT INSTRUCTIONS**: You MUST completely remove (with minimal changes) any instructions, states, or retry count loops related to handling silence, no-input, or unresponsive users from the prompt instructions. All generic timeout and no-input events are strictly handled in the background by the native `before_model_callback`. You MUST identify any intermediate nudge questions (e.g. "Are you still there?") and final transfer/escalation messages from the source agent's instructions, and customize the callback responses below to match those original utterances exactly. - Example Callback Implementation to assume: ```python for part in callback_context.get_last_user_input(): text_input = part.text.lower() if part.text else "" if "no user activity detected" in text_input or "sys.no-input" in text_input or "sys.no-match" in text_input or text_input.strip() == "": retry = callback_context.variables.get("no_input_retry_count", 0) + 1 callback_context.variables["no_input_retry_count"] = retry if retry >= 3: # Customize text verbatim from source agent's final transfer message return LlmResponse.from_parts([ Part.from_text("We haven't heard from you. Let me transfer you to support."), Part.from_agent_transfer(agent="Session_Termination_Agent") ]) # Customize text verbatim from source agent's intermediate silence nudge return LlmResponse.from_parts([Part.from_text("Are you still there?")]) ``` ### SOURCE AGENT INSTRUCTIONS: {instruction} ### REGISTERED TOOLS AVAILABLE: {tools} You MUST return ONLY the finalized, clean XML output. Do NOT wrap the response in markdown blocks (like ```xml) or include conversational filler. """, } STAGE_2_TOOL_MOCK_OPTIMIZATION = { "system": "You are an expert CXAS Python Integration Engineer.", "template": """ You are an expert CXAS Python Integration Engineer. Your task is to optimize this Python tool code by adding a high-quality, realistic happy-path "mock mode" execution branch. To construct a high-quality, correct mock response, you MUST analyze exactly how this tool is consumed by the referencing agents' instructions and callbacks. The mock response MUST contain all the expected keys, values, and structures needed for the calling agent to successfully advance its execution logic along the happy path. ### REFERENCING AGENTS CONTEXT (INSTRUCTIONS & CALLBACKS): {agents_context} ### OPTIMIZATION RULES (NON-NEGOTIABLE): 1. **NO SIGNATURE OR PARAMETER CHANGES**: You MUST NOT change the function signature, parameter list, docstrings, imports, or any existing function parameters. 2. **NATIVE STATE MOCK MODE**: - At the very beginning of the function, you MUST check the global `mock_mode` variable by calling `get_variable("mock_mode")` natively. - If it is True, immediately return a comprehensive, highly realistic happy-path dictionary that contains all necessary data, keys, and expected structures matching the tool's purpose and the calling agent's expectations. 3. **PRESERVE ORIGINAL BUSINESS LOGIC**: All original, actual API/integration logic MUST be left completely untouched in the `else` block. ### ORIGINAL PYTHON FUNCTION CODE: {python_code} You MUST return ONLY the finalized, complete, executable Python code. Do NOT wrap the code in markdown code fences (like ```python) or include conversational filler. """, }