Руководство по таблицам данных — документация AIKraft Agents

В этом руководстве описано, как отображать структурированные данные с помощью блоков datatable и spreadsheet, а также как использовать инструмент transform_data для больших наборов данных.

Обзор

AIKraft Agents поддерживает три способа отображения табличных данных:

Формат	Подходит для	Интерактивность
Таблица Markdown	Небольшие простые данные (3–4 строки)	Нет
Блок `datatable`	Результаты запросов, сравнения, любые данные, которые пользователи могут сортировать или фильтровать	Сортировка, фильтрация, группировка, поиск
Блок `spreadsheet`	Финансовые отчёты, выгрузки, данные, которые пользователи могут скачать в формате .xlsx	Сортировка, экспорт в Excel/CSV

Ключевой принцип: для наборов данных с 20 и более строками используйте инструмент transform_data, чтобы записать данные в JSON-файл и сослаться на него через поле "src", а не встраивать все строки напрямую. Это значительно снижает расход токенов и стоимость.

Встроенные таблицы (небольшие наборы данных)

Для наборов данных менее 20 строк встраивайте данные непосредственно в markdown-блок:

Datatable

terminaljson

{
  "title": "Top Users",
  "columns": [
    { "key": "name", "label": "Name", "type": "text" },
    { "key": "revenue", "label": "Revenue", "type": "currency" },
    { "key": "growth", "label": "Growth", "type": "percent" },
    { "key": "active", "label": "Active", "type": "boolean" },
    { "key": "tier", "label": "Tier", "type": "badge" }
  ],
  "rows": [
    { "name": "Acme Corp", "revenue": 4200000, "growth": 0.152, "active": true, "tier": "Enterprise" },
    { "name": "StartupCo", "revenue": 85000, "growth": -0.03, "active": true, "tier": "Starter" }
  ]
}

Spreadsheet

terminaljson

{
  "filename": "q4-revenue.xlsx",
  "sheetName": "Revenue",
  "columns": [
    { "key": "month", "label": "Month", "type": "text" },
    { "key": "revenue", "label": "Revenue", "type": "currency" }
  ],
  "rows": [
    { "month": "October", "revenue": 125000 },
    { "month": "November", "revenue": 142000 }
  ]
}

Справочник по типам столбцов

Тип	Формат ввода	Отображается как	Пример ввода	Пример вывода
`text`	Произвольная строка	Обычный текст	`"John Doe"`	John Doe
`number`	Число	Форматированное число	`1500000`	1,500,000
`currency`	Сырое число (без форматирования)	Сумма в долларах	`4200000`	$4,200,000
`percent`	Дробное число (диапазон 0–1)	Процент с цветом	`0.152`	+15.2% (зелёный)
`boolean`	`true`/`false`	Да/Нет	`true`	Да
`date`	Строка с датой	Форматированная дата	`"2025-01-15"`	Jan 15, 2025
`badge`	Строка	Цветная плашка статуса	`"Active"`	Active (плашка)

Важные замечания:

currency — передавайте сырое число, а не отформатированную строку. Значение 4200000 отображается как $4,200,000.
percent — передавайте в виде дробного числа. Значение 0.152 отображается как +15.2%. Положительные значения — зелёным, отрицательные — красным.
boolean — используйте фактические значения true/false, а не строки.

Таблицы на основе файлов (большие наборы данных)

Когда использовать

Используйте инструмент transform_data + поле "src", когда:

набор данных содержит 20 и более строк — встраивание 100 строк обходится примерно в $1+ токенов;
данные поступают из большого ответа API или результата инструмента;
необходимо отфильтровать, преобразовать или агрегировать сырые данные перед отображением;
данные представлены в формате CSV, TSV или неструктурированного текста, требующего разбора;
необходимо объединить данные из нескольких источников.

Инструмент transform_data

Инструмент transform_data выполняет скрипт в изолированном дочернем процессе, который читает входные файлы и записывает структурированный JSON-вывод.

Параметры:

Параметр	Тип	Описание
`language`	`"python3"` \| `"node"` \| `"bun"`	Интерпретатор скрипта
`script`	string	Исходный код скрипта преобразования
`inputFiles`	string[]	Пути к входным файлам относительно каталога сессии
`outputFile`	string	Имя выходного файла (записывается в каталог `data/` сессии)

Соглашения по путям:

Входные файлы указываются относительно каталога сессии. Расположение:
- long_responses/tool_result_abc.txt — сохранённые результаты инструментов;
- data/previous_output.json — результат предыдущего преобразования;
- attachments/data.csv — файлы, прикреплённые пользователем.
Выходной файл указывается относительно каталога data/ сессии. Достаточно указать имя файла (например, "transactions.json").

Соглашения по аргументам скрипта:

Пути к входным файлам передаются как позиционные аргументы командной строки.
Последний аргумент всегда является путём к выходному файлу.
Python: sys.argv[1:-1] — входные файлы, sys.argv[-1] — путь к выходному файлу.
Node/Bun: process.argv.slice(2, -1) — входные файлы, process.argv.at(-1) — путь к выходному файлу.

Схема JSON-вывода

Выходной файл должен содержать корректный JSON в одном из следующих форматов:

Полный формат (рекомендуется):

terminaljson

{
  "title": "Recent Transactions",
  "columns": [
    { "key": "date", "label": "Date", "type": "date" },
    { "key": "amount", "label": "Amount", "type": "currency" },
    { "key": "status", "label": "Status", "type": "badge" }
  ],
  "rows": [
    { "date": "2025-01-15", "amount": 250.00, "status": "Completed" }
  ]
}

Формат только со строками:

terminaljson

{
  "rows": [
    { "date": "2025-01-15", "amount": 250.00, "status": "Completed" }
  ]
}

Или просто массив:

terminaljson

[
  { "date": "2025-01-15", "amount": 250.00, "status": "Completed" }
]

Семантика слияния: при использовании поля "src" встроенные columns и title в markdown-блоке имеют приоритет над значениями из файла. Это позволяет определить типы столбцов в блоке, а строки получать из файла.

Ссылка на результат

После успешного выполнения transform_data возвращается абсолютный путь к выходному файлу. Используйте именно этот путь как значение поля "src" в блоке datatable или spreadsheet:

terminaljson

{
  "src": "/absolute/path/returned/by/transform_data",
  "title": "Recent Transactions",
  "columns": [
    { "key": "date", "label": "Date", "type": "date" },
    { "key": "amount", "label": "Amount", "type": "currency" },
    { "key": "status", "label": "Status", "type": "badge" }
  ]
}

Важно: всегда используйте абсолютный путь из результата инструмента transform_data. Не конструируйте относительные пути вручную.

Полный пример рабочего процесса

Пользователь спрашивает: «Покажи все транзакции Stripe за прошлый месяц»

Шаг 1: Вызовите API Stripe через MCP-инструмент — получите большой JSON-ответ.

Шаг 2: Вызовите transform_data для извлечения и структурирования данных:

terminalbash

transform_data({
  language: "python3",
  script: "import json, sys\nwith open(sys.argv[1]) as f:\n    data = json.load(f)\nrows = [{\n    'id': t['id'],\n    'date': t['created'],\n    'amount': t['amount'] / 100,\n    'status': t['status'].title(),\n    'customer': t.get('customer_email', 'N/A')\n} for t in data.get('data', data.get('transactions', []))]\nwith open(sys.argv[-1], 'w') as f:\n    json.dump({'rows': rows}, f)",
  inputFiles: ["long_responses/stripe_result.txt"],
  outputFile: "transactions.json"
})

Шаг 3: Выведите блок datatable, используя абсолютный путь из результата transform_data:

terminaljson

{
  "src": "/absolute/path/from/transform_data/result",
  "title": "Stripe Transactions — Last Month",
  "columns": [
    { "key": "id", "label": "ID", "type": "text" },
    { "key": "date", "label": "Date", "type": "date" },
    { "key": "amount", "label": "Amount", "type": "currency" },
    { "key": "status", "label": "Status", "type": "badge" },
    { "key": "customer", "label": "Customer", "type": "text" }
  ]
}

Частые паттерны и рецепты

Ответ JSON API → Datatable

Самый распространённый паттерн. Извлечение полей из JSON-ответа API:

Python:

terminalpython

import json, sys

with open(sys.argv[1]) as f:
    data = json.load(f)

# Обработка распространённых форматов ответов API
items = data.get('data', data.get('items', data.get('results', data)))
if not isinstance(items, list):
    items = [items]

rows = [{
    'id': item['id'],
    'name': item.get('name', ''),
    'created': item.get('created_at', ''),
} for item in items]

with open(sys.argv[-1], 'w') as f:
    json.dump({'rows': rows}, f)

CSV/TSV → Spreadsheet

Разбор данных CSV для экспорта в spreadsheet:

Python:

terminalpython

import csv, json, sys

with open(sys.argv[1]) as f:
    reader = csv.DictReader(f)
    rows = list(reader)

# Автоматическое определение столбцов из заголовков CSV
columns = [{'key': k, 'label': k.replace('_', ' ').title(), 'type': 'text'} for k in rows[0].keys()] if rows else []

with open(sys.argv[-1], 'w') as f:
    json.dump({'columns': columns, 'rows': rows}, f)

Объединение данных из нескольких источников

Объединение данных из нескольких результатов инструментов:

Python:

terminalpython

import json, sys

# sys.argv[1:-1] — входные файлы, sys.argv[-1] — выходной файл
with open(sys.argv[1]) as f:
    users = {u['id']: u for u in json.load(f)['data']}
with open(sys.argv[2]) as f:
    orders = json.load(f)['data']

rows = [{
    'order_id': o['id'],
    'customer': users.get(o['user_id'], {}).get('name', 'Unknown'),
    'amount': o['total'],
    'status': o['status'],
} for o in orders]

with open(sys.argv[-1], 'w') as f:
    json.dump({'rows': rows}, f)

Вызов:

terminalbash

transform_data({
  language: "python3",
  script: "...",
  inputFiles: ["..."],
  outputFile: "..."
})

Обзор

Встроенные таблицы (небольшие наборы данных)

Datatable

Spreadsheet

Справочник по типам столбцов

Таблицы на основе файлов (большие наборы данных)

Когда использовать

Инструмент transform_data

Схема JSON-вывода

Ссылка на результат

Полный пример рабочего процесса

Частые паттерны и рецепты

Ответ JSON API → Datatable

CSV/TSV → Spreadsheet

Объединение данных из нескольких источников

Нужен такой агент в вашей компании?