Agent Task Status

GET

/v1/agent/task/{task_id}

curl --request GET \
  --url https://api.cloud.agentums.ru/v1/agent/task/example \
  --header 'Authorization: Bearer <token>'

• Прод

Чем кончилась фоновая задача, task_id которой уехал в кадре tool_end.

require_key, а не rate_limit(): эндпоинт опросный (клиент дёргает его раз в секунду до готовности), и лимитер выключил бы ровно тот сценарий, ради которого он есть. Разбор состояния — общий с /objects/pdf-status и /objects/content-status (services.task_status), третьей копии правил «что считать завершённым» не заводим.

БЕЗОПАСНОСТЬ. task_id не несёт владельца: любой аутентифицированный пользователь может подставить сюда чужой id (и подобрать — это uuid4 задачи Celery). Поэтому наружу уходит ровно два вида сведений:

• ok — булев исход. По нему злоумышленник узнаёт только то, что какая-то задача с таким id завершилась успешно; ни файла, ни владельца, ни операции в этом нет;
• note — человеческая подпись. Имя файла в неё попадает ТОЛЬКО если объект из результата задачи принадлежит спрашивающему (_resolve_filename скоупит запрос по tenant+owner). Чужой файл даёт нейтральное «Готово» — то есть по чужому task_id нельзя достать ни имя файла, ни его id. Соседние /pdf-status//content-status отдают object_id и filename любому аутентифицированному по task_id и оправдываются тем, что открытие файла всё равно проверяет владельца; имя файла — уже само по себе содержимое, и повторять это здесь незачем: агентному клиенту хватает ok и подписи.

Authorizations

• bearerAuth

Parameters

Path Parameters

task_id

required

Task Id

string

Responses

200

Successful Response

Media typeapplication/json

AgentTaskStatus

Ответ GET /agent/task/{task_id} в форме события task_done из SSE-контракта: клиент кладёт его в тот же обработчик, что и кадр из стрима.

done — единственное поле сверх контракта, и оно обязательно: без него «ещё выполняется» и «выполнилось с ошибкой» неотличимы (оба ok=false), и клиент либо покажет ошибку раньше времени, либо будет опрашивать вечно.

object

done

Done

boolean

filename

Filename

string

""

note

Note

string

""

object_id

Object Id

string

""

ok

Ok

boolean

stage

Stage

string

""

step

Step

integer

0

steps

Steps

integer

0

task_id

required

Task Id

string

type

Type

string

default: task_done

Example

{
  "done": false,
  "filename": "",
  "note": "",
  "object_id": "",
  "ok": false,
  "stage": "",
  "step": 0,
  "steps": 0,
  "type": "task_done"
}

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

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}