Run

Runs the agent over a message and handles the requires_action state.

Updated on Aug 10, 2026

The run returns completed when the agent answered on its own, or stops at requires_action when it asked for a tool — then it is your turn: run the actual function and return the result so the run can continue.

POSThttps://agents.hinow.ai/v1/agents/{agent_id}/runBearer

Runs the agent over a message.

Parâmetros

agent_iduuid· pathobrigatório
Run completed or stopped waiting for tools
messagestring· bodyobrigatório
Returns the results of the requested tools and resumes the run.
thread_idstring· body
Bearer
variablesobject· body
One item per pending call: `{ call_id, output }`.
historyarray· body
Run resumed
streamboolean· body
Padrão `true` (SSE). Com `false`, a resposta chega em um único JSON ao final.
eventsstring· body
Verbosidade do stream: `full` (padrão), `messages` ou `minimal`. Ver Eventos da execução.
versionstring· body
`published` (padrão) ou `draft` — roda o rascunho como sandbox. Rascunho inválido responde `422` com o relatório do validador.

Respostas

200Stream SSE (padrão) ou JSON único (stream: false).

{
  "agent_id": "aaaaaaaa-0000-4000-8000-000000900002",
  "thread_id": "1c7a4741-29cb-4b1a-95dd-6412dd773f0e",
  "response": "ok",
  "finish_reason": "stop",
  "usage": {"cost": 0.00046, "input_tokens": 824, "output_tokens": 692, "time": 6.99}
}

400message ausente ou corpo inválido.

401API key ausente, inválida ou revogada.

404Agente inexistente, não publicado ou fora do escopo da sua key.

502Um nó do workflow falhou — a mensagem traz a causa real.

{"error": {"message": "Variáveis obrigatórias não informadas: caso", "type": "agent_error"}}

Forma equivalente: POST /v1/agents/run com "agent_id" no corpo. As duas aceitam os mesmos campos.

Exemplos

curl -N -X POST https://agents.hinow.ai/v1/agents/SEU_AGENT_ID/run \
  -H "Authorization: Bearer hi_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "olá!", "variables": {"caso": "..."}}'

curl -X POST https://agents.hinow.ai/v1/agents/SEU_AGENT_ID/run \
  -H "Authorization: Bearer hi_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "olá!", "stream": false}'

const res = await fetch(
  'https://agents.hinow.ai/v1/agents/SEU_AGENT_ID/run',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer hi_SUA_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'olá!' }),
  },
);

const reader = res.body.getReader();
const decoder = new TextDecoder();
let threadId;

for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split('\n')) {
    if (!line.startsWith('data: ')) continue; // ": keepalive" é comentário
    const event = JSON.parse(line.slice(6));
    if (event.type === 'thread') threadId = event.thread_id; // guarde!
    if (event.type === 'agent_message') console.log(event.data.content);
    if (event.type === 'done') console.log('usage:', event.data.usage);
  }
}

import httpx, json

with httpx.stream(
    "POST",
    "https://agents.hinow.ai/v1/agents/SEU_AGENT_ID/run",
    headers={"Authorization": "Bearer hi_SUA_API_KEY"},
    json={"message": "olá!"},
    timeout=600,
) as r:
    for line in r.iter_lines():
        if not line.startswith("data: "):
            continue  # ": keepalive" é comentário
        event = json.loads(line[6:])
        if event["type"] == "thread":
            thread_id = event["thread_id"]  # guarde!
        elif event["type"] == "agent_message":
            print(event["data"]["content"])
        elif event["type"] == "done":
            print("usage:", event["data"]["usage"])

A resposta em streaming

O primeiro evento é sempre o thread — guarde o thread_id: é ele que continua a conversa e permite parar a execução. Depois vêm os eventos de progresso (nós, ferramentas, falas dos agentes) e, por fim, o done com o usage consolidado.

trecho real de um runjson

data: {"type":"thread","thread_id":"2586cf3b-d291-40ce-97f3-932531699022"}

data: {"type":"workflow_node_start","data":{"node_id":"juiz-intro","node_type":"agent"}}

data: {"type":"agent_message","data":{"content":"Apresento o caso aos jurados...","sender":{"name":"Juiz"}}}

: keepalive

data: {"type":"done","usage":{"cost":0.0075,"input_tokens":18240,"output_tokens":3105,"time":371.2}}

Conversas

Mande o mesmo thread_id no próximo request e o agente continua de onde parou, com a memória do turno anterior. Variáveis do nó Início marcadas como persist também sobrevivem entre turnos — um contador de rodadas, por exemplo.

Quanto tempo demora

O primeiro evento chega em dezenas de milissegundos; o total depende inteiramente do workflow. Medidas reais na plataforma:

Cenário	Tempo típico
Primeiro evento (`thread`)	~35 ms
Agente simples (1 nó, modelo rápido)	2–7 s
Agente com ferramentas (busca, RAG, código)	10–60 s
Multi-agente (debate, votação, loops)	minutos — um júri com 3 rodadas mediu 6–10 min

Timeouts no seu lado

Prefira SSE com timeout generoso (10 min+) para workflows complexos. O servidor manda um comentário : keepalive a cada 15 s — a conexão nunca fica muda, mesmo durante uma chamada longa de modelo. Atenção: desconectar o SSE aborta o run.

Erros

Status	type	Quando acontece
400	invalid_request_error	`message` ausente ou corpo malformado.
401	authentication_error	Key ausente, inválida ou revogada.
402	insufficient_funds	Créditos esgotados — o run para na primeira inferência.
404	not_found_error	Agente inexistente, não publicado, ou de outro projeto/organização.
422	validation_error	Só com `version: draft`: o rascunho não passa no validador — o corpo traz o relatório completo.
502	agent_error	Um nó falhou; a mensagem traz a causa (ex.: variável obrigatória faltando, modelo indisponível).
504	timeout_error	Nenhum evento por 5 minutos — o stream é encerrado.

Cobrança

Você paga por inferência dentro do run, não por execução. O done (ou o JSON síncrono) traz o usage com custo, tokens e tempo. Se você parar no meio, paga só o que rodou.

Was this page helpful?