Structured Output

Tools surface structured results as durable tool_result frames. Richer views can also emit a panel_open frame, while large or persisted payloads are retrieved through the artifacts API.

Each tool_result and any following panel_open arrives before the terminal message frame, wrapped in the durable WebSocket envelope.

Read the tool-result envelope

Normal tool results use this shape:

{
  "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
  "turn_id": "73e602c9-2058-4a9d-aa0d-3df063ea1d5b",
  "seq": 4,
  "event": "tool_result",
  "data": {
    "tool": "data_analytics__execute_sql",
    "output": {"kind": "table", "columns": [], "rows": [], "row_count": 0, "truncated": false},
    "tool_call_id": "tc_1",
    "depth": 1,
    "skill": "data_analytics"
  }
}

The tool payload is frame.data.output, not frame.data itself. tool_call_id, depth, and skill are correlation metadata and can be absent. Saved-query turns are the compatibility exception: their synthetic tool_result.data is the bare legacy payload {rows, row_count, truncated, note?} and has no output wrapper. Normalize both forms before rendering:

function toolOutput(data: Record<string, unknown>) {
  return "output" in data ? data.output : data;
}

SQL tables

Successful SQL results have output.kind: "table":

{
  "tool": "data_analytics__execute_sql",
  "output": {
    "kind": "table",
    "columns": [
      {"name": "project_name", "type_hint": "string", "sql_type": "nvarchar"},
      {"name": "budget", "type_hint": "number", "sql_type": "decimal"}
    ],
    "rows": [
      ["Al Raha Beach Tower", 12800000],
      ["Green Spine Boulevard", 31600000]
    ],
    "row_count": 2,
    "truncated": false,
    "integration_id": "b320ce13-4cf0-4f83-a5e5-0e8bf0a51629",
    "error": null,
    "code": null,
    "success": true,
    "access_control": null,
    "retryable": null,
    "reason": null
  },
  "tool_call_id": "tc_1",
  "depth": 1,
  "skill": "data_analytics"
}

columns and rows are parallel: each row is a value array in column order. type_hint is a renderer-friendly coarse type; sql_type can be absent. row_count is the number of returned rows, and truncated: true means more rows matched upstream. Values are unformatted and can include null. Recoverable failures use kind: "error"; access-control refusals use kind: "denied". Inspect kind before assuming table fields exist, and display the returned error or reason without retrying denied queries from the client.

Saved-query result

The first result for a saved-query turn uses rows as objects for backward compatibility:

{
  "rows": [
    {"project_name": "Al Raha Beach Tower", "budget": 12800000},
    {"project_name": "Green Spine Boulevard", "budget": 31600000}
  ],
  "row_count": 2,
  "truncated": false
}

When truncated is true, an explanatory note can also be present.

Charts

The chart tool returns a renderer-neutral chart spec capped at 2,000 rows inline and persists the fuller spec produced from the scoped query as an artifact:

{
  "tool": "data_analytics__plot_data",
  "output": {
    "kind": "chart",
    "chart_spec": {
      "chart_type": "bar",
      "title": "Top Projects by Budget",
      "x": {"field": "project_name", "label": "Project", "type": "string"},
      "y": [{"field": "budget", "label": "Budget (AED)", "type": "number"}],
      "data": {
        "columns": [
          {"name": "project_name", "type_hint": "string"},
          {"name": "budget", "type_hint": "number"}
        ],
        "rows": [
          ["Al Raha Beach Tower", 12800000],
          ["Green Spine Boulevard", 31600000]
        ],
        "truncated": false
      },
      "options": {"stacked": false}
    },
    "artifact_id": "1b9d4c22-77ea-4d0f-8a3e-9f0c2b6a1e55",
    "artifact_url": "",
    "error": null,
    "code": null,
    "success": true,
    "access_control": null,
    "retryable": null,
    "reason": null
  }
}

Supported chart_type values are bar, line, pie, scatter, area, and histogram. chart_spec.data is columnar (columns plus 2D rows), not an array of row objects. The inline chart_spec.data.rows array contains at most 2,000 rows. When more rows were available, it contains the first 2,000 and chart_spec.data.truncated is true. That flag can also be true when the scoped query itself reached an upstream result limit. The chart_spec artifact is persisted before the inline row cap is applied, so its payload can contain more than 2,000 rows. Inspect the artifact payload’s data.truncated value to distinguish upstream query truncation: true there means the persisted query result was also truncated, while false means the artifact contains the full result returned for that chart. The artifact is fuller than the inline response, not an unbounded export. The current artifact_url value is empty; construct /v1/artifacts/{artifact_id} from artifact_id. Render the inline spec immediately or retrieve the fuller spec later with Get Artifact and Get Artifact Payload. Generic analytics agents can instead produce a rendered HTML artifact:

{
  "tool": "data_analytics__plot_data",
  "output": {
    "kind": "artifact_ref",
    "artifact_id": "9f2c1a7b-3e4d-4f8a-9c2b-1d6e5a0f7b8c",
    "content_type": "text/html"
  }
}

This payload is also fetched through /v1/artifacts/{artifact_id} and /payload. The external API has no /v1/plots route.

Full table exports

Full table exports and the row_count / truncated artifact-status fields are in a forthcoming API deployment. The currently deployed API revision does not expose this additive contract yet.

When the agent exports a complete SQL result set, it returns an XLSX artifact reference rather than putting the rows on the stream:

{
  "tool": "data_analytics__export_query_results",
  "output": {
    "kind": "artifact_ref",
    "artifact_id": "2c0e5d33-88fb-4e10-9b4f-a01d3c7b2f66",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "filename": "project-budget.xlsx",
    "row_count": 42831,
    "truncated": false
  }
}

The export has its own 250,000-row ceiling. Its truncated flag describes that export ceiling, not the much smaller inline SQL preview cap. Poll Get Artifact if needed, then download /v1/artifacts/{artifact_id}/payload.

Typed panels

Schedules, editable tables, media grids, decks, and exports can be persisted as panels and announced with panel_open after the producing tool result:

{
  "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
  "turn_id": "73e602c9-2058-4a9d-aa0d-3df063ea1d5b",
  "seq": 7,
  "event": "panel_open",
  "data": {
    "panel_id": "7d1e9a44-2b6c-4f0a-8e3d-5c9f1a2b3c4d",
    "type": "schedule",
    "state": {"type": "schedule", "schedule_id": "39763c28-37db-48cb-a1df-20b34b6f127d", "version": 3},
    "entity_id": "39763c28-37db-48cb-a1df-20b34b6f127d",
    "entity_version": 3,
    "tool_call_id": "tc_2",
    "chat_message_id": "58fc85f1-18dd-43d0-9267-f31a06074c44"
  }
}

Fetch full state with Get Panel using panel_id. entity_id, entity_version, tool_call_id, and chat_message_id can be null.

Handling example

const BASE = "https://api.trellis.sh";

async function handleFrame(frame: any, token: string) {
  if (frame.event === "tool_result") {
    const output: any = toolOutput(frame.data);

    if (output.kind === "table") {
      renderTable(output.columns, output.rows, output.truncated);
    } else if (!output.kind && Array.isArray(output.rows)) {
      renderRecordRows(output.rows, output.truncated);
    } else if (output.kind === "chart") {
      renderChartSpec(output.chart_spec);
    } else if (output.kind === "artifact_ref") {
      const status = await fetch(`${BASE}/v1/artifacts/${output.artifact_id}`, {
        headers: {Authorization: `Bearer ${token}`},
      }).then((response) => response.json());
      showArtifact(status, output);
    } else if (output.kind === "error" || output.kind === "denied") {
      showToolError(output.error ?? output.reason);
    }
  } else if (frame.event === "panel_open") {
    const panel = await fetch(
      `${BASE}/v1/chats/${frame.chat_id}/panels/${frame.data.panel_id}`,
      {headers: {Authorization: `Bearer ${token}`}},
    ).then((response) => response.json());
    renderPanel(panel.type, panel.content);
  }
}

All artifact, panel, chat, and job reads on the external API are scoped to the authenticated member and return 404 rather than disclose another member’s resources.

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Read the tool-result envelope

SQL tables

Saved-query result

Charts

Full table exports

Typed panels

Handling example

​Read the tool-result envelope

​SQL tables

​Saved-query result

​Charts

​Full table exports

​Typed panels

​Handling example

Read the tool-result envelope

SQL tables

Saved-query result

Charts

Full table exports

Typed panels

Handling example