База знаний агента

Как работает база знаний

У каждого агента своя папка файлов. Отдельной таблицы нет: список — это содержимое папки, файл с тем же именем заменяет прежний. Агент видит папку как /knowledge, только для чтения: файлы можно искать по смыслу и по словам и читать целиком, pdf, docx и doc читаются как текст.

Сейчас база знаний подключается в долгих задачах, которые ассистент запускает сам: составить документ, перевести файл, собрать отчёт. Для этого у ассистента должна быть включена выдача файлов (capability_files_output, см. Возможности). После загрузки или удаления файла поисковый индекс пересобирается при следующем обращении агента.

Файлы видит только агент, которому они загружены, и только у своего ассистента. При удалении агента папка не удаляется — снимите файлы до удаления.

Лимит	Значение
Форматы	txt, md, markdown, csv, json, html, htm, yml, yaml, pdf, docx, doc, rtf
Размер файла	10 МБ
Всего у агента	100 МБ
Файлов у агента	200
Имя файла	До 180 символов. Путь, .. и управляющие символы отрезаются, остаётся базовое имя

Список файлов

GET /agents/{agentId}/knowledge

Параметр	Тип	Обяз.	Описание
agentId	integer	да	Путь. Агент ассистента, к которому у ключа есть доступ

curl -s "$BASE/agents/$AGENT/knowledge" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "files": [
    { "name": "kb-test.txt", "size": 80, "updated_at": "2026-09-25T19:52:03+00:00" },
    { "name": "rules.md", "size": 50, "updated_at": "2026-09-25T19:52:06+00:00" }
  ],
  "total_size": 130,
  "limits": {
    "max_file_size": 10485760,
    "max_total_size": 104857600,
    "max_files": 200,
    "extensions": ["txt", "md", "markdown", "csv", "json", "html", "htm", "yml", "yaml", "pdf", "docx", "doc", "rtf"]
  }
}

Файлы отсортированы по имени, size — в байтах.

Загрузить файлы

Принимает файлы формой или текст прямо в теле — второе удобно, чтобы завести регламент одной командой без файла на диске. Пакет обрабатывается пофайлово: отклонённый файл не мешает остальным. Файл с именем, которое уже есть, заменяет прежний ("replaced": true).

POST /agents/{agentId}/knowledge

Параметр	Тип	Обяз.	Описание
agentId	integer	да	Путь
files[]	file	нет	Тело, multipart/form-data. Один или несколько файлов
name	string	нет	Тело. Имя файла с расширением, если текст приходит в content
content	string	нет	Тело. Содержимое файла name

Файлом:

curl -s -X POST "$BASE/agents/$AGENT/knowledge" \
  -H "Authorization: Bearer $KEY" \
  -F "files[]=@kb-test.txt" \
  -F "files[]=@canva.js"

{
  "success": true,
  "files": [{ "name": "kb-test.txt", "size": 80, "replaced": false }],
  "errors": [{ "name": "canva.js", "reason": "bad_name_or_extension" }]
}

Текстом:

curl -s -X POST "$BASE/agents/$AGENT/knowledge" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "rules.md", "content": "# Правила\n\nОтвечать коротко."}'

{ "success": true, "files": [{ "name": "rules.md", "size": 50, "replaced": false }], "errors": [] }

Ответ 201, если сохранился хотя бы один файл. Если ни одного — 422 с причинами в errors.

reason	Когда
bad_name_or_extension	Расширение не из списка или имя пустое после очистки
empty	Пустой файл
too_large	Файл больше 10 МБ
too_many_files	У агента уже 200 файлов, а это не замена
quota_exceeded	Превышен общий объём 100 МБ
nothing_to_save	В запросе нет ни files[], ни пары name и content

Удалить файл

DELETE /agents/{agentId}/knowledge/{name}

Параметр	Тип	Обяз.	Описание
agentId	integer	да	Путь
name	string	да	Путь. Имя файла, закодированное для адреса (%20 вместо пробела)

curl -s -X DELETE "$BASE/agents/$AGENT/knowledge/rules.md" \
  -H "Authorization: Bearer $KEY"

{ "success": true, "deleted": "rules.md" }

Ошибки

HTTP	Когда
404	{"error": "Agent not found or access denied"} — агента нет или нет доступа к его ассистенту
404	{"error": "File not found"} — при удалении файла нет
422	{"error": "Bad file name"} — при удалении имя с недопустимым расширением
422	Загрузка: ни один файл не принят, причины в errors

Дальше

• Агенты — объект агента и методы.
• Свойства config — остальные настройки агента.
• Возможности — выдача файлов и другие флаги ассистента.