Перейти к содержимому
Agentum Cloud для разработчиков

Agent Chat

POST
/v1/agent/chat
curl --request POST \
  --url https://api.cloud.agentums.ru/v1/agent/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agent_slug": "example", "attachment_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "channel_chat_id": 0, "channel_members": [ { "display_name": "", "role": "", "user_id": 1, "username": "" } ], "channel_user_id": 0, "collection_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "history": [ { "content": "example", "role": "example" } ], "include_subfolders": true, "inline_attachments": [ { "filename": "", "text": "example" } ], "query": "example", "scope_object_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "session_id": "example", "web_search": true }'

Агент с инструментами: сам решает, что сделать с файлами, и стримит ход работы.

В отличие от /chat агент действует: ищет, конвертирует, переводит, собирает PDF, заводит поручения. Ответ — поток SSE-событий: start, token (кусочки текста), tool_start / tool_end, paused, error, done.

Форма потока — два правила, которые легко нарушить, и оба стоят потерянных данных:

  • paused — конец потока. done за ним НЕ придёт: агент упёрся в опасный инструмент (перезапись файла, необратимое действие) и ждёт решения. Продолжают ран через POST /agent/continue, передавая решения по ВСЕМ инструментам из события одним вызовом — не упомянутый инструмент молча не выполнится.
  • error — не конец потока. За кадром с ошибкой могут прийти ещё токены и done. Выйти из цикла по error значит потерять хвост ответа.

session_id из start/done продолжает разговор следующим вызовом. collection_id ограничивает работу папкой, scope_object_ids (до 25) — конкретными файлами: это сужение поиска инструментов, а не выдача доступа. web_search — политика «можно ли вообще», решение идти в сеть принимает сам агент.

Ошибки приходят до потока, обычным ответом: 503 — агентный режим выключен на сервере, 402 — исчерпан месячный лимит.

Authorizations

Заголовок раздела «Authorizations»

Parameters

Заголовок раздела «Parameters»

Header Parameters

Заголовок раздела «Header Parameters»
x-hidden-token
Any of:
string

Request Bodyrequired

Заголовок раздела «Request Bodyrequired»
Media typeapplication/json
AgentChatRequest
object
agent_slug
Any of:
string
<= 64 characters
attachment_ids
Attachment Ids
Array<string>
<= 5 items
channel_chat_id
Channel Chat Id
integer
0
channel_members
Channel Members
Array<object>
<= 200 items
ChannelMemberIn

Один участник канала: адрес плюс то, как его зовут и окликают.

object
display_name
Display Name
string
"" <= 200 characters
role
Role
string
"" <= 200 characters
user_id
required
User Id
integer
username
Username
string
"" <= 64 characters
channel_user_id
Channel User Id
integer
0
collection_id
Any of:
string format: uuid
history
History
Array<object>
<= 50 items
AskTurnIn
object
content
required
Content
string
role
required
Role
string
include_subfolders
Include Subfolders
boolean
default: true
inline_attachments
Inline Attachments
Array<object>
<= 5 items
InlineAttachmentIn

Разовое вложение: имя файла + УЖЕ извлечённый текст. Файла в облаке нет и не будет — это контекст, который живёт только в запросе (и в истории чата как имя).

object
filename
Filename
string
"" <= 255 characters
text
required
Text
string
>= 1 characters <= 50000 characters
query
required
Query
string
>= 1 characters <= 8000 characters
scope_object_ids
Scope Object Ids
Array<string>
<= 25 items
session_id
Any of:
string
web_search
Web Search
boolean
default: true

Responses

Заголовок раздела «Responses»

200

Заголовок раздела «200»

Поток событий SSE: кадры data: {…} с полем type (start|token|tool_start|tool_end|paused|error|done). paused — терминальный кадр (ран ждёт /agent/continue), error — НЕ терминальный: за ним ещё могут прийти токены и done.

Examplegenerated
example

422

Заголовок раздела «422»

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}