Агенты и харнесс

Как с Артефакторием работают внешние агенты по MCP, встроенный агент и прогоны харнесса: инструменты artifact_*, загрузка больших файлов, поиск по смыслу, результаты шагов.

Артефакторий одинаково доступен людям и агентам: файл, который положил агент, человек видит на экране, а файл человека агент находит поиском и читает.

Внешний агент по MCP

Агент, подключённый по MCP (Claude Code, Cursor и другие), работает с файлами инструментами artifact_*. Проект берётся из подключения, project_id указывать не нужно. Файл задаётся слагом (AF-ARTF-12).

Инструмент	Что делает
`artifact_upload`	Сохранить файл: текст (`content`) или двоичный (`content_base64`) до 16 МБ. Описание обязательно
`artifact_complete_upload`	Завершить загрузку большого файла (см. ниже)
`artifact_list`	Содержимое каталога, поиск по имени, описанию и слагу, корзина (`trash: true`)
`artifact_get`	Свойства файла и «Где используется»
`artifact_read_text`	Текст файла до 1 МБ прямо в ответ; можно конкретную версию
`artifact_download_url`	Ссылка на скачивание любого файла, живёт 5 минут
`artifact_update`	Сменить имя, описание, теги, метаданные. Теги и метаданные заменяются целиком
`artifact_move`	Перенести один или несколько файлов в каталог
`artifact_delete`	Удалить в корзину; используемый файл — только с `confirm: true`
`artifact_folder_create`	Создать каталог вместе с недостающими родителями
`artifact_quota`	Сколько занято, сколько осталось, есть ли предупреждение

Корзина (восстановление, «удалить навсегда»), операции с каталогами, кроме создания, и история версий — только на экране Артефактория.

Сохранить результат и сослаться на него

агент сохранил замер и сослался на него

artifact_upload(folder: "reports/bench/", name: "latency-2026-10-05.md",
                content: "# p95 до и после кеша\n…",
                description: "Замер p95 /api/search до и после кеша Redis, 10k запросов",
                tags: ["bench", "search"])
  → { artifact: { slug: "AF-ARTF-12", … } }

add_comment(slug: "AF-TASK-901", body: "[done] p95 упал с 480 до 95 мс — замер AF-ARTF-12")

Описание обязательно не из бюрократии: содержимое файлов в поиск не попадает, и через месяц файл найдут только по описанию. Пишите одно-два предложения о том, что в файле и зачем он.

Новая версия

Загрузка в занятое имя без флага отклоняется: «name already exists in this folder». Чтобы обновить файл, сохранив слаг и ссылки, передайте new_version: true.

Большие файлы

Больше 16 МБ (до 5 ГБ) файл грузится в три шага:

artifact_upload(large: true, size_bytes: …, sha256: "…", …) — агент получает ссылки для загрузки по частям.
Агент загружает части по выданным ссылкам (HTTP PUT).
artifact_complete_upload(upload_id: …, parts: [{part_number, etag}, …]) — Flownix сверяет размер и контрольную сумму и только после этого создаёт файл.

Незавершённая загрузка живёт 24 часа. Если контрольная сумма не сошлась, файл не создаётся.

Поиск по смыслу

найти файл по смыслу

rag_query(kind_filter: "artifact", query: "почему упала миграция на проде")

Ищет по имени, каталогу, описанию и тегам. Найденное открывайте через artifact_get или artifact_read_text, а не get_node. Без kind_filter файлы находятся вместе с задачами и документами.

Ссылки нод на файлы

Кроме упоминания в тексте, агент может явно добавить файл в ссылки ноды:

shell

set_references(slug: "AF-TASK-42", ref_slugs: ["AF-TASK-40", "AF-ARTF-31"])

У файла появится связь вида «ссылка». Подробно о видах связей — Ссылки и «Где используется».

Встроенный агент

Агент в чате Flownix работает с Артефакторием сам — инструменты подключаются, когда разговор касается файлов.

Что он делает:

находит файлы по смыслу и по имени, показывает их свойства и «Где используется»;
читает текстовые файлы до 1 МБ — ТЗ, логи, отчёты, Markdown, код;
для картинок, PDF, архивов и больших файлов даёт ссылку на скачивание;
сохраняет свои отчёты и сводки как текстовые файлы с описанием и называет слаг;
переименовывает, описывает, переносит файлы, создаёт каталоги, показывает квоту;
новую версию существующего файла создаёт только по вашей просьбе;
удаляет только после вашего «Разрешить», а если файл используется — сначала объясняет, какие ссылки сломаются.

Чего он не может: прочитать двоичный файл и загрузить большой файл — у него нет доступа к сети и файловой системе. Поэтому, чтобы агент поработал с ТЗ, загрузите его текстом (.md, .txt), а не PDF или DOCX.

Харнесс

Шаги прогона харнесса обмениваются файлами через Артефакторий:

Участник сохраняет результат шага через artifact_upload с harness_run_id — источником файла будет «Прогон харнесса».
При завершении шага (work_complete) участник передаёт слаги своих файлов в result_artifact_ids. У файла в «Где используется» появится прогон с видом «результат».
Следующие шаги получают эти слаги на вход автоматически — в input_artifact_ids, по рёбрам графа, в порядке шагов и без повторов. У стартовых шагов входных файлов нет.

Так отчёт аналитика сам доходит до критика, а критика — до судьи, и в каждом файле видно, какой прогон его произвёл.