Execuções (runs)

Rodar um assistente sobre a thread: ciclo de vida, streaming, cancelamento e run steps.

Atualizado em 10 de ago. de 2026

A execução junta as três peças: o assistente (a configuração), a thread (a conversa) e o instante. O run tem ciclo de vida próprio — você o cria, ele processa, e o resultado vira uma mensagem na thread.

POSThttps://api.hinow.ai/v1/threads/{thread_id}/runsBearer

Executa um assistente sobre a thread.

Parâmetros

thread_idstring· pathobrigatório
assistant_idstring· bodyobrigatório
streamboolean· body
true liga o SSE (eventos abaixo).
modelstring· body
Sobrepõe o modelo do assistente só neste run.
instructionsstring· body
Substitui as instruções neste run.
additional_instructionsstring· body
Acrescenta ao fim das instruções, sem substituí-las.
additional_messagesarray· body
Mensagens acrescentadas à thread antes de rodar.
toolsarray· body
Sobrepõe as ferramentas neste run.
temperaturenumber· body
top_pnumber· body
max_completion_tokensinteger· body
Corte de saída — estourou, o run termina incomplete.
truncation_strategyobject· body
{"type": "last_messages", "last_messages": N} limita o histórico enviado ao modelo.
response_formatstring | object· body
metadataobject· body

Respostas

200O objeto thread.run (ou o stream SSE, com stream: true)

400Thread já tem um run ativo, ou parâmetro inválido

404Thread ou assistente inexistente

O ciclo de vida

Status	Significado
`queued`	Aceito, aguardando vaga de execução.
`in_progress`	O modelo está trabalhando.
`requires_action`	O modelo chamou suas funções — envie os resultados em submit_tool_outputs (veja Chamada de funções).
`completed`	Terminou; a resposta está na thread.
`incomplete`	Terminou cortado — `incomplete_details.reason` diz o motivo (`max_completion_tokens`, `max_tool_loops`).
`cancelling` / `cancelled`	Cancelamento pedido / concluído.
`failed`	Erro de execução — detalhes em `last_error`.
`expired`	Passou do prazo de 10 minutos sem concluir (inclui `requires_action` sem resposta).

Sem streaming: polling

RUN=$(curl -s https://api.hinow.ai/v1/threads/$THREAD/runs \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"assistant_id": "asst_..."}' | jq -r .id)

# consulte até sair de queued/in_progress
curl -s https://api.hinow.ai/v1/threads/$THREAD/runs/$RUN \
  -H "Authorization: Bearer hi_SUA_API_KEY" | jq '{status, usage}'

Com streaming: SSE

Com stream: true, a resposta é um stream text/event-stream com os mesmos eventos da OpenAI — os SDKs e handlers existentes funcionam sem mudança:

thread.run.created → thread.run.queued → thread.run.in_progress
thread.run.step.created / .in_progress / .delta / .completed
thread.message.created / .in_progress / .delta (o texto chega aqui) / .completed
terminal: thread.run.completed, .requires_action, .incomplete, .failed, .cancelled, .expired
e por fim done com data: [DONE].

Thread + run numa chamada

POSThttps://api.hinow.ai/v1/threads/runsBearer

Cria a thread e já executa — o atalho para conversas novas.

Parâmetros

assistant_idstring· bodyobrigatório
threadobject· body
{"messages": [...], "metadata": {...}} — o corpo de um create thread.
streamboolean· body

Respostas

200O run, com thread_id da thread recém-criada

Cancelar

curl -s -X POST https://api.hinow.ai/v1/threads/$THREAD/runs/$RUN/cancel \
  -H "Authorization: Bearer hi_SUA_API_KEY"
# → status: "cancelling"; em seguida "cancelled".
# O cancelamento aborta inclusive a chamada de modelo em voo.

Run steps: o que aconteceu lá dentro

Cada run registra seus passos — message_creation (a resposta) e tool_calls (ferramentas, com argumentos e resultados). É a trilha de auditoria da execução:

curl -s "https://api.hinow.ai/v1/threads/$THREAD/runs/$RUN/steps?order=asc" \
  -H "Authorization: Bearer hi_SUA_API_KEY"

Uma execução por vez

Uma thread não aceita dois runs simultâneos: o segundo volta com 400 invalid_request_error (“Thread ... already has an active run ...”). Em interfaces de chat, desabilite o envio enquanto a execução anterior não terminar. Runs expiram em 10 minutos — inclusive os parados em requires_action.

Esta página foi útil?