Skill: yash-kavaiya/cx-agent-studio (version 1.0.0)

--- name: cx-agent-studio description: Guide and instructions for using Google Customer Experience Agent Studio (CX Agent Studio). Use when creating conversational agents, writing or structuring instructions with XML tags, setting up few-shot examples, or building evaluation test cases (Golden or Scenario). --- # CX Agent Studio Customer Experience Agent Studio (CX Agent Studio) is a minimal code conversational agent builder built on the Agent Development Kit (ADK), representing the evolution of Dialogflow CX. ## Core Capabilities - **AI-Augmented Building**: Generate agents using Gemini with a 1-2 sentence goal. - **Bi-directional Streaming**: Ultra-low latency voice interactions. - **Asynchronous Tool Calling**: Maintains natural conversation flow during backend calls. ## Quick Actions ### 1. Generating an Agent with AI To generate an agent automatically: - Provide a clear 1-2 sentence goal. - Optionally provide up to 5 knowledge documents (under 8MB total) like FAQs or tool catalogs. *Note: Only works for the root agent and empty agents.* ### 2. Architecture & Design - **Agents**: Root (steering) agents orchestrate tasks and delegate to sub-agents. Read `references/agents.md`. - **Flows**: Integrate legacy Dialogflow CX flows for deterministic business logic (auth, sequential validation). Read `references/flows.md`. - **Variables**: Store and retrieve runtime conversation data. Read `references/variables.md`. ### 3. Writing Agent Instructions Agent instructions guide the model's behavior, persona, and tool/agent usage. - **Syntax References**: - Variables: `{variable_name}` - Tools: `{@TOOL: tool_name}` - Sub-Agents: `{@AGENT: Agent Name}` - **For complex instructions or recommended XML formatting**, read: `references/instructions.md` - **Best Practices**: Start simple, use specific/structured instructions, flat parameter structures. Read `references/best-practices.md`. ### 4. Tools & Callbacks - **Tools**: Connect your agent to external systems. Wrap complex APIs in Python tools to reduce context overhead. Read `references/tools.md`. - **Callbacks**: Advanced Python hooks (`before_agent_callback`, `after_model_callback`, etc.) to control execution, validate states, or inject custom JSON payloads. Read `references/callbacks.md`. ### 5. Guardrails & Safety - **Guardrails**: Protect against prompt attacks and enforce Responsible AI policies. Read `references/guardrails.md`. ### 6. Agent Evaluation Evaluation ensures agent performance via automated test cases. - **Scenario Test Cases**: AI-generated simulated user conversations based on a user goal. - **Golden Test Cases**: Specific, ideal conversation paths for regression testing. - **For detailed evaluation metrics, personas, and test case creation**, read: `references/evaluation.md`

path: references/agents.md
content: # Agents in CX Agent Studio

An agent application is composed of one or more agents:
- **Root agent (steering agent)**: Primary entry point and orchestrator. Handles main user interactions, understands overall goals, and delegates tasks.
- **Sub-agent (child agent)**: Specialized agent for specific tasks/domains (e.g., searching a database). Promotes modularity.

Root agents can invoke sub-agents, and sub-agents can invoke other sub-agents.

## Language Support
Design agents in English. They automatically detect the end-user's language and respond in the same language. Default language and unsupported language handling can be configured in agent application settings.

## Settings
- **Global interactions**: Global model, language controls, ambient sounds, response length, allow user interruptions, agent lock.
- **Advanced**: Silence timeout, dtmf, logging (data sharing, redaction, Cloud Logging, BigQuery), parallel/sequential tool execution, and global instructions.
- **Agent specific**: Name, model override, description (used by other agents), and custom callback code.

path: references/best-practices.md
content: # Best Practices in CX Agent Studio

This guide provides best practices for designing reliable agent applications.

## General
- **Start simple**: Begin with simple use cases and scale up to complicated ones.
- **Specific instructions**: Unambiguous, well-organized, grouped by topics, and easy for a human to follow.
- **Structured instructions**: Use the restructure feature for XML formatted instructions (more reliable).

## Tools
- **Wrap APIs**: Wrap external APIs with Python tools to obfuscate unnecessary data. Return only relevant fields to reduce context and latency (Context Engineering).
- **Deterministic behavior**: Use tools and callbacks for deterministic behavior (e.g., canned responses or sequential validations).
- **Chaining tool calls**: Avoid instructing the agent to call multiple tools sequentially. Define a single tool that calls the others to reduce token usage and hallucination probability.
- **Clear definitions**: Distinct names, unused tools removed, flattened snake_case parameters. Avoid abbreviations (`pnum` -> `phone_number`).

## Development Workflow
- **Collaboration**: Define a clear development process using third-party version control (import/restore) or built-in version control (snapshots).
- **Versions**: Create immutable snapshots of the agent. Use Semantic Versioning (`v1.0.0`) or descriptive names (`pre-prod-instruction-changes`). Include detailed descriptions.
- **End-to-End testing**: Test external system integrations.

## Evaluations
- **Use evaluations**: Ensure agent reliability by setting expectations on agents and their APIs.

path: references/callbacks.md
content: # Callbacks in CX Agent Studio

Callbacks let you hook into an agent's execution process using Python code to observe, customize, and control behavior at specific points.

## Callback Types
1. **`before_agent_callback(callback_context)`**:
   - Called before the agent is invoked.
   - Purpose: Setup resources, validate session state, avoid agent invocation.
   - Return: `Optional[Content]`. If set, agent is skipped.

2. **`after_agent_callback(callback_context)`**:
   - Called after the agent completes.
   - Purpose: Cleanup tasks, post-execution validation, modify final state.
   - Return: `Optional[Content]`. If set, replaces agent output.

3. **`before_model_callback(callback_context, llm_request)`**:
   - Called before model request.
   - Purpose: Inspect/modify the model request, prompt validation, caching.
   - Return: `Optional[LlmResponse]`. If set, model call is skipped.

4. **`after_model_callback(callback_context, llm_response)`**:
   - Called after a model response is received.
   - Purpose: Reformat responses, censor sensitive info, parse structured data to variables, handle errors.
   - Return: `Optional[LlmResponse]`. If set, replaces model response.

5. **`before_tool_callback(tool, input, callback_context)`**:
   - Called before tool calls.
   - Purpose: Inspect/modify tool arguments, auth checks, tool caching.
   - Return: `Optional[dict[str, Any]]`. If set, tool execution is skipped and dict is returned to the model.

6. **`after_tool_callback(tool, input, callback_context, tool_response)`**:
   - Called after tool completion.
   - Purpose: Post-processing tool results, save parts to variables.
   - Return: `Optional[dict[str, Any]]`. If set, overrides the tool response provided to the model.

## Custom Payloads (`custom_payloads`)
Used for supplementary non-textual data (JSON) within an agent's response to interact with external systems/clients (escalation, rich content widgets, routing).
- Set using `before_model_callback` or `after_model_callback`.
- Value is not visible to the LLM.
- Used as a `Blob` with mime_type `application/json`.
- `Part.from_json(data=payload_string)`

path: references/evaluation.md
content: # CX Agent Studio Evaluation Reference

Evaluation helps automate testing, catch regressions, and measure agent quality via test cases.

## Test Case Types

### 1. Scenario Test Cases
- Uses AI to simulate various user conversations based on a high-level **user goal** (e.g., "Securely book a specific room at a chosen hotel").
- Helps explore edge cases without manually writing conversational paths.
- Can be saved as **Golden Conversations** once they work well.
- **Scenario Expectations**:
  - Message expected from end-user or agent.
  - Tool call with expected inputs/outputs.
  - Conditions: Must have, Must not have, After tool call, Variable value.

### 2. Golden Test Cases
- Defines specific, ideal conversation paths for **regression testing**.
- Evaluates if the agent's behavior and tool calls match this ideal path.
- Created via: Simulator, Conversation history, from Scratch, Simulated Scenario, or CSV Batch Upload.
- **Golden Expectations**:
  - Message: Text response from agent matching the expectation semantically.
  - Tool Call: Agent calling a specific tool and response (with input args).
  - Agent Handoff: Conversation transfer to human or another bot.

## Evaluation Metrics

Metrics calculate the agent's performance.

| Metric | Type | Description |
| --- | --- | --- |
| **Tool Correctness** | Golden/Scenario | Percentage of expected parameters matched. Unexpected calls fail the golden test but don't impact this score. |
| **User Goal Satisfaction** | Scenario | Binary metric (0=no, 1=yes). Measures if simulated user believes goals were achieved based on `user_goal` and transcript. |
| **Hallucinations** | Golden/Scenario | Identifies claims not justified by context (variables, history, tools, instructions). Only computed for turns with tool calls. |
| **Semantic Match** | Golden | Measures how well observed agent utterance matches expected utterance (0=contradictory to 4=consistent). |
| **Scenario Expectations** | Scenario | Satisfactory behavior (0=no, 1=yes). Includes tool call and agent response expectations. |
| **Task Completion** | Scenario | Jointly measures user goal achievement and correct agent behavior. |

## AI Issue Discovery

When running 3 or more evaluations, enable **Find issues with AI** to generate a downloadable `loss_report`. You can interact with the helper agent via "Ask Gemini" to explain problems and suggest fixes.

## Personas

Simulated user personas customize scenario tests (e.g., adding age, location, or motivations) to ensure the agent interacts appropriately with expected human users during runtime. Created under "Persona management" and used by selecting the persona during an evaluation run.

path: references/flows.md
content: # Flows in CX Agent Studio

Dialogflow CX flows can be integrated into CX Agent Studio agents.
- Flow-based agents hand off conversation to the flow until `END_SESSION` is reached, returning to the steering agent.
- Agent apps send user input to flows using the `DetectIntent` API.
- Require permissions: `Customer Engagement Suite Service Agent` needs `Dialogflow API Client` role.

## Migration Best Practices
- **Isolate Agent Types**: Create new CX Agent Studio agents for new use cases and maintain Dialogflow CX agents for old ones via a routing layer.
- **Highly Deterministic Business Logic**: Use flows for sequential data collections and validations or authentication flows based on session parameters.
  - Do NOT use for canned responses or intent classification.
- **Flows as Blackboxes**: Treat flows as encapsulated black boxes. Convey info through explicit input/output parameters. Modification to parameter collection logic upstream should not disrupt downstream flows.

path: references/guardrails.md
content: # Guardrails in CX Agent Studio

Guardrails are checks and balances protecting agent applications (model input and output).

## Prompt Guard
Protection against prompt attacks ("ignore your instructions").
- Outcomes: Say exactly, Handoff to an agent, Generate a response, or Custom.

## Blocklist
Prevent certain words/phrases.
- Matches: Whole words, Any mention, Regex pattern.
- Blocked content from: User input, Agent response.
- Outcomes: Say exactly, Handoff, Generate response.

## Safety
Enforce Responsible AI practices.
- Levels: Relaxed, Balanced, Strict.
- Outcomes: Say exactly, Handoff, Generate response, Custom.

## Rules
Build your own using:
- Natural language instructions.
- Code (after_model_callback python code).
- Outcomes: Say exactly, Handoff, Generate response.

path: references/instructions.md
content: # Instructions in CX Agent Studio

Agent instructions provide detailed natural-language guidance for the model (goal, persona, tool/sub-agent use).

## Syntax
- **Variables**: `{variable_name}`
- **Tools**: `{@TOOL: tool_name}`
- **Sub-Agents**: `{@AGENT: Agent Name}`

## Structured XML Format
It is highly recommended to use XML formatting for instructions (via the "Restructure instructions" button) to improve model instruction handling:
- `<role>`: Core function.
- `<persona>`: Personality, tone, behavioral guidelines.
  - `<primary_goal>`: Agent's main objective.
- `<constraints>`: Rules and limitations.
- `<taskflow>`: Outline of conversation flows.
  - `<subtask>`: Part of the flow containing steps.
    - `<step>`: Individual step.
      - `<trigger>`: Condition that initiates a step.
      - `<action>`: Action the agent should take.
- `<examples>`: Few-shot examples.

## Inline Few-Shot Examples
Use sparingly to guide behavior for complex formatting or nuanced logic. Format inside `<examples>` tags using `[user]`, `[model]`, ```tool_code```, and ```tool_outputs``` blocks.

## Best Practices
- Chunking & whitespace: Use line breaks between ideas. Max 1-2 sentences per block.
- Bold important data (Names, Prices, Dates, Order Numbers).
- Use lists for multiple items or steps.
- **Global Instructions**: Define instructions for *all* agents in the app setting (brand tone, DOs/DON'Ts, shared variables).

path: references/tools.md
content: # Tools in CX Agent Studio

Tools connect agents to external systems or inline code to fetch, update, format, or analyze info.

## Tool Types
- **Client function**: Code executed client-side, not by the agent.
- **Data store**: AI-generated responses from website/uploaded data.
- **Website data store**: Search info from websites.
- **Cloud storage data store**: Search info from unstructured documents (RAG).
- **File search**: Upload files / RAG to agent.
- **Google Search**: Grounding with Google Search.
- **Integration Connector**: Pre-configured Connections.
- **MCP tools**: Connect to a Model Context Protocol server.
- **OpenAPI**: Connect to an external API using an OpenAPI schema.
- **Python code**: Provide Python code inline as a tool.
- **Salesforce / ServiceNow**: Connect to external SaaS platforms.
- **System tools**: Built-in common tasks.
- **Widget tools**: Flexible rich UI interaction.

## Best Practices
- **Wrap APIs**: Wrap complex external APIs with Python tools to obfuscate unnecessary data and reduce context tokens (Context Engineering).
- **Tool Chaining**: Don't instruct agents to call multiple tools sequentially. Instead, wrap them in a single Python tool that calls the others.
- **Clear Names/Descriptions**: Semantically meaningful distinct names, high-quality descriptions. Use flattened parameters in snake_case.

path: references/variables.md
content: # Variables in CX Agent Studio

Variables store and retrieve runtime conversation data.

## Types
- Text: String values
- Number: Numeric values
- Yes/No: Boolean values
- Custom Object: Schema for the object
- List: List of variables (comma delimited)

## Referencing
- Use braces `{variable_name}` in instructions. CX Agent Studio replaces these with runtime values.

## Updating
- Agents cannot update variables directly.
- **Tools and callbacks** can update variables.
- Using Python tools:
  ```python
  context.state["variable_name"] = value
  ```

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)