UI Resource Tool

Return rich, structured UI components from agent responses

The UI Resource Tool enables agents to return rich, structured UI components instead of plain text responses. When called, it renders a Jinja2 template with data from the conversation and displays the result as an interactive card in the chat.

Overview

Tool Name: ui_resource

When an agent calls this tool, it:

1. Selects a UI Resource template by name
2. Passes context data (extracted from the conversation) to the template
3. Renders the Jinja2 template with the data
4. Returns the rendered HTML to the user in an iframe

Configuration

Create a UI Resource Tool

1. Navigate to AI Studio > Tools
2. Click Create Tool
3. Select UI Resource as the tool type
4. Configure the tool:
   • Name: Internal identifier (e.g., product_card)
   • Display Name: User-facing name (e.g., Show Product)
   • Description: What this tool does — helps the AI decide when to call it
   • Prompt: Instructions for when the agent should use this tool
5. In Additional Info, set the template name to the UI Resource template this tool renders
6. Define the Input Schema — the data fields the agent will extract from the conversation
7. Click Save
8. Assign the tool to your agent in AI Studio > Agents > Tools tab

Tool-Specific Settings

Setting	Default	Description
Template Name	(required)	Name of the UI Resource template to render
Forward User Auth	Off	Pass user JWT to template context
Auto-Resize	On	Automatically resize the iframe to fit content

Input Schema

Define what data the agent should extract and pass to the template. The field names must match the variables used in your template.

Example — a notification card tool:

Parameter	Type	Description
card_type	enum (info, warning, success, error)	Card style
title	string	Card title
message	string	Card content
actions	string (JSON array)	Action buttons

Tool Response Format

The tool returns rendered HTML to the chat widget:

{
  "mcp_ui_resource": {
    "type": "rawHtml",
    "htmlString": "<div>...</div>",
    "uri": "ui-resource://template-id"
  },
  "template_name": "product-card",
  "rendered_successfully": true
}

---

Troubleshooting

Template not rendering

1. Check the template name in Additional Info matches exactly
2. Verify the template is marked as active in AI Studio > UI Resources
3. Ensure the agent passes all required fields defined in the context schema

Content cut off or scrollbars appear

1. Verify Auto-Resize is enabled in the tool configuration
2. Avoid fixed heights in your template CSS
3. Use flexible layouts (flexbox, grid)

Agent not using the tool

1. Review the tool’s Description and Prompt — make them specific about when to use it
2. Verify the tool is assigned to the agent
3. Check the input schema matches what the agent can extract from the conversation

---

Related

• UI Resources — Create and manage templates (syntax, schema, configuration)
• UI Resources Guide — Design patterns, accessibility, and testing
• AI Template Editor — Edit templates with natural language
• Tools Overview — General tool configuration