render_ui

Emit a Generative UI component spec — cards, tables, stats, forms, and interactive elements — directly in the chat.

render_ui

Emits a json-render.dev component spec in the chat. The agent calls this when it wants to display rich visual UI — dashboards, scorecards, data tables, action panels — without needing an external API call.

For an overview of all three Generative UI surfaces (this tool, custom tool responses, and inline artifacts), see Generative UI.

Parameters

Name	Type	Required	Description
spec	object	yes	A json-render.dev component tree. Must have root, elements, and optionally state.
interactive	boolean	no	When true, buttons and form inputs in the spec are live. The user’s submission arrives on the next turn as a tool result. Default false.

Spec structure

{
  "root": "elementId",
  "elements": {
    "elementId": {
      "type": "card",
      "props": { "title": "...", "subtitle": null },
      "children": ["childId"]
    },
    "childId": { ... }
  },
  "state": { "fieldName": "defaultValue" }
}

• root — the id of the top-level element to render.
• elements — a flat map of element id → definition. Each element has type, props, and children (array of element ids).
• state — initial values for any input elements that use { "$bindState": "/field" }. Required when interactive: true and inputs are present.

See Generative UI → Component reference for all available components and props.

Returns

Static render:

{ "action": "render", "interactive": false }

Interactive render — returns an interaction_id. The user’s submitted values arrive on the next turn:

{ "status": "submitted", "result": { "values": { "fieldName": "value" } } }

On spec validation failure: { "error": "...", "details": { "hint": "..." } }.

---

Examples

Static metrics card

{
  "spec": {
    "root": "card",
    "elements": {
      "card": {
        "type": "card",
        "props": { "title": "Account overview", "subtitle": null },
        "children": ["stats", "divider", "kv"]
      },
      "stats": {
        "type": "list",
        "props": { "direction": "horizontal", "gap": "lg" },
        "children": ["spent", "remaining", "sessions"]
      },
      "spent": {
        "type": "stat",
        "props": { "label": "Credits used", "value": 1240,
                   "change": null, "changeType": null, "prefix": null, "suffix": null },
        "children": []
      },
      "remaining": {
        "type": "stat",
        "props": { "label": "Credits remaining", "value": 3760,
                   "change": null, "changeType": null, "prefix": null, "suffix": null },
        "children": []
      },
      "sessions": {
        "type": "stat",
        "props": { "label": "Sessions this month", "value": 47,
                   "change": "+12%", "changeType": "up", "prefix": null, "suffix": null },
        "children": []
      },
      "divider": { "type": "divider", "props": {}, "children": [] },
      "kv": {
        "type": "key_value",
        "props": {
          "items": [
            { "key": "Plan",      "value": "Pro" },
            { "key": "Renews",    "value": "2026-06-01" },
            { "key": "API calls", "value": "382 this month" }
          ]
        },
        "children": []
      }
    },
    "state": {}
  }
}

---

Interactive action panel

Set interactive: true so the submit button works. The user’s selection returns to the agent on the next turn.

{
  "interactive": true,
  "spec": {
    "root": "panel",
    "elements": {
      "panel": {
        "type": "card",
        "props": { "title": "Resolve ticket #1042", "subtitle": null },
        "children": ["details", "divider", "form"]
      },
      "details": {
        "type": "key_value",
        "props": {
          "items": [
            { "key": "Customer", "value": "Jane Smith" },
            { "key": "Issue",    "value": "Unable to export CSV" },
            { "key": "Priority", "value": "High" }
          ]
        },
        "children": []
      },
      "divider": { "type": "divider", "props": {}, "children": [] },
      "form": {
        "type": "form",
        "props": { "title": "Resolution", "description": null },
        "children": ["actionSelect", "notesInput", "submitBtn"]
      },
      "actionSelect": {
        "type": "input",
        "props": {
          "kind": "select",
          "name": "action",
          "label": "Action",
          "placeholder": null,
          "required": true,
          "value": { "$bindState": "/action" },
          "options": [
            { "value": "fix_sent",  "label": "Fix sent — mark resolved" },
            { "value": "workaround","label": "Shared workaround — awaiting feedback" },
            { "value": "escalate",  "label": "Escalate to engineering" }
          ],
          "min": null, "max": null
        },
        "children": []
      },
      "notesInput": {
        "type": "input",
        "props": {
          "kind": "textarea",
          "name": "notes",
          "label": "Notes",
          "placeholder": "Optional internal notes...",
          "required": false,
          "value": { "$bindState": "/notes" },
          "options": null, "min": null, "max": null
        },
        "children": []
      },
      "submitBtn": {
        "type": "button",
        "props": { "label": "Submit", "variant": "primary", "disabled": null },
        "on": { "press": { "action": "submit" } },
        "children": []
      }
    },
    "state": { "action": "", "notes": "" }
  }
}

---

Status table

{
  "spec": {
    "root": "card",
    "elements": {
      "card": {
        "type": "card",
        "props": { "title": "Integration status", "subtitle": null },
        "children": ["table"]
      },
      "table": {
        "type": "table",
        "props": {
          "caption": null,
          "columns": ["Service", "Status", "Last sync"],
          "rows": [
            ["Slack",          "Connected",    "2 min ago"],
            ["GitHub",         "Connected",    "14 min ago"],
            ["Jira",           "Needs re-auth", "3 days ago"],
            ["Google Calendar","Disconnected", "—"]
          ]
        },
        "children": []
      }
    },
    "state": {}
  }
}

---

Alert with badges

{
  "spec": {
    "root": "card",
    "elements": {
      "card": {
        "type": "card",
        "props": { "title": "Deployment summary", "subtitle": "v2.4.1 → production" },
        "children": ["notice", "metrics"]
      },
      "notice": {
        "type": "alert",
        "props": {
          "title": "Deployment succeeded",
          "message": "All 3 services deployed and health checks passed.",
          "variant": "success"
        },
        "children": []
      },
      "metrics": {
        "type": "list",
        "props": { "direction": "horizontal", "gap": "md" },
        "children": ["b1", "b2", "b3"]
      },
      "b1": {
        "type": "badge",
        "props": { "label": "3 services", "variant": "default" },
        "children": []
      },
      "b2": {
        "type": "badge",
        "props": { "label": "0 errors", "variant": "success" },
        "children": []
      },
      "b3": {
        "type": "badge",
        "props": { "label": "12s rollout", "variant": "default" },
        "children": []
      }
    },
    "state": {}
  }
}

---

Call from your own custom tool

export async function handle(input, ctx) {
  return await ctx.tools.render_ui({
    interactive: false,
    spec: {
      root: 'card',
      elements: {
        card: {
          type: 'card',
          props: { title: input.title, subtitle: null },
          children: ['kv'],
        },
        kv: {
          type: 'key_value',
          props: {
            items: input.items.map((i) => ({ key: i.k, value: i.v })),
          },
          children: [],
        },
      },
      state: {},
    },
  });
}

async def handle(input, ctx):
    return await ctx.tools.render_ui({
        'interactive': False,
        'spec': {
            'root': 'card',
            'elements': {
                'card': {
                    'type': 'card',
                    'props': {'title': input['title'], 'subtitle': None},
                    'children': ['kv'],
                },
                'kv': {
                    'type': 'key_value',
                    'props': {
                        'items': [{'key': i['k'], 'value': i['v']} for i in input['items']]
                    },
                    'children': [],
                },
            },
            'state': {},
        },
    })

Notes

• Always registered when render_ui is enabled for the agent.
• For interactive renders where the submit action is destructive, pair with confirm_action + commit_action — render_ui does not provide an anti-hallucination gate on its own.
• To include a file download card alongside a visual layout, call surface_file first and embed the returned downloadUrl in a key_value element.