> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Resources

> Create rich, interactive UI components for agent responses

UI Resources are Jinja2-based HTML templates that agents render dynamically in chat. Instead of plain text, agents can display cards, tables, forms, and other interactive elements.

## How It Works

1. You create a **UI Resource template** with HTML, CSS, and Jinja2 placeholders
2. You create a **UI Resource Tool** and link it to the template
3. When an agent calls the tool, it passes data to the template
4. The template renders and displays in the chat as an iframe

```
Agent → UI Resource Tool → Template + Data → Rendered HTML → User
```

***

## Creating Templates

<Steps>
  <Step title="Open the Template Builder">
    Navigate to **AI Studio** > **UI Resources** > **Create Template**
  </Step>

  <Step title="Configure Settings">
    | Setting     | Description                        |
    | ----------- | ---------------------------------- |
    | Name        | Unique identifier for the template |
    | Description | What this template displays        |
    | Active      | Enable or disable the template     |
  </Step>

  <Step title="Define the Context Schema">
    The context schema specifies what data your template expects. The agent and tool use this schema to know what fields to extract from the conversation.

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "product_name": {
          "type": "string",
          "description": "Name of the product"
        },
        "price": {
          "type": "number",
          "description": "Price in dollars"
        },
        "features": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of features"
        }
      },
      "required": ["product_name", "price"]
    }
    ```
  </Step>

  <Step title="Write the Template">
    Use Jinja2 syntax to create dynamic HTML. Include `<style>` tags for CSS within the template.

    ```html theme={null}
    <div class="product-card">
      <h2>{{ product_name }}</h2>
      <p class="price">${{ price }}</p>

      {% if features %}
      <ul class="features">
        {% for feature in features %}
        <li>{{ feature }}</li>
        {% endfor %}
      </ul>
      {% endif %}
    </div>

    <style>
      .product-card { padding: 20px; border: 1px solid #e0e0e0; border-radius: 8px; }
      .price { font-size: 24px; color: #0069ED; }
    </style>
    ```
  </Step>

  <Step title="Add Preview Data">
    Provide sample data to test rendering in the preview pane:

    ```json theme={null}
    {
      "product_name": "Premium Plan",
      "price": 99.99,
      "features": ["Unlimited users", "Priority support", "Advanced analytics"]
    }
    ```
  </Step>
</Steps>

***

## Template Syntax (Jinja2)

### Variables

```html theme={null}
{{ variable_name }}
{{ user.email }}
{{ items[0].name }}
```

### Conditionals

```html theme={null}
{% if condition %}
  Content when true
{% elif other_condition %}
  Alternative content
{% else %}
  Default content
{% endif %}
```

### Loops

```html theme={null}
{% for item in items %}
  <div>{{ item.name }} - {{ item.value }}</div>
{% else %}
  <p>No items found</p>
{% endfor %}
```

Loop utilities: `loop.index` (1-indexed), `loop.first`, `loop.last`, `loop.length`.

### Filters

| Filter                | Example                         | Description                                     |
| --------------------- | ------------------------------- | ----------------------------------------------- |
| default               | `{{ value \| default("N/A") }}` | Fallback for missing values                     |
| upper / lower / title | `{{ text \| upper }}`           | Change case                                     |
| truncate              | `{{ text \| truncate(100) }}`   | Limit text length                               |
| round                 | `{{ price \| round(2) }}`       | Round numbers                                   |
| join                  | `{{ tags \| join(', ') }}`      | Join array elements                             |
| urlencode             | `{{ query \| urlencode }}`      | URL-encode strings                              |
| safe                  | `{{ trusted_html \| safe }}`    | Output raw HTML (use only with trusted content) |

### Conditional CSS Classes

```html theme={null}
<span class="badge {{ 'success' if status == 'active' else 'warning' }}">
  {{ status }}
</span>
```

### Macros

Define reusable components within a template:

```html theme={null}
{% macro button(text, url, style='primary') %}
<a href="{{ url }}" class="btn btn-{{ style }}">{{ text }}</a>
{% endmacro %}

{{ button('Learn More', '/about', 'secondary') }}
{{ button('Buy Now', '/checkout') }}
```

> **⚠️ WARNING**: Templates run in a sandboxed environment. Some Jinja2 features are disabled for security.

***

## Connecting Templates to Agents

After creating a template, you need a UI Resource Tool to make it available to an agent:

1. Go to **AI Studio** > **Tools** > **Create Tool**
2. Select **UI Resource** as the tool type
3. Set the template name in Additional Info
4. Define the input schema (matching the template's context schema)
5. Write a prompt describing when the agent should display this template
6. Assign the tool to your agent

See [UI Resource Tool](../tools/ui-resource-tool) for detailed configuration.

***

## AI-Powered Editing

The template builder includes an AI assistant that can modify templates using natural language:

1. Open a template in **AI Studio** > **UI Resources**
2. Go to the **Template** tab
3. Click the **AI Edit** button (sparkles icon)
4. Describe your changes: "Add a button", "Make it responsive", "Use blue tones"

See [AI Template Editor](./ai-template-editor) for details.

***

## Configuration Reference

### Template Fields

| Setting          | Description                                 |
| ---------------- | ------------------------------------------- |
| Name             | Unique template identifier                  |
| Description      | What the template displays                  |
| Template Content | Jinja2 HTML template with `<style>` tags    |
| Context Schema   | JSON Schema defining expected data fields   |
| Preview Data     | Sample data for testing in the preview pane |
| Active           | Enable or disable the template              |
| Version          | Auto-incremented on each change             |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Template not rendering">
    1. Verify the template name matches exactly in the tool's Additional Info
    2. Check the template is marked as active
    3. Verify context data matches the schema requirements
    4. Review the template for Jinja2 syntax errors
  </Accordion>

  <Accordion title="Variables showing as empty">
    1. Check context data is being passed correctly by the tool
    2. Verify variable names match the schema keys exactly
    3. Use `{{ variable | default('N/A') }}` for optional fields
  </Accordion>

  <Accordion title="Styling not applied">
    1. Include a `<style>` tag within the template
    2. Use inline styles for critical elements
    3. Avoid referencing external stylesheets
  </Accordion>

  <Accordion title="Content cut off">
    1. Verify Auto-Resize is enabled in the tool configuration
    2. Avoid fixed heights in CSS
    3. Use flexible layouts (flexbox, grid)

    ***
  </Accordion>
</AccordionGroup>

## Related

* [UI Resource Tool](../tools/ui-resource-tool) — Tool configuration and input schema
* [UI Resources Guide](../guides/ui-resources-guide) — Design patterns, accessibility, and testing
* [AI Template Editor](./ai-template-editor) — Edit templates with natural language