Agent runs

Um agent run é uma tarefa autônoma: o modelo planeja, chama ferramentas (web, código, os dados do workspace, criação de arquivos, um navegador real), verifica e entrega um resultado — transmitido passo a passo. Diferente do chat, ele é responsável pela tarefa de ponta a ponta.

Iniciar um run

POST/v1/workspaces/{workspace_id}/agent/runs —

inicia o run. O run é desacoplado da conexão: este endpoint devolve um pequeno objeto JSON imediatamente e o motor continua trabalhando de forma desanexada. Acompanhe o stream ao vivo com GET …/attach (abaixo).

Integração mínima — um campo. Envie apenas {"task": "…"} e pronto. A plataforma roteia automaticamente para o melhor modelo, escolhe e chama as ferramentas certas (busca na web, sua base de conhecimento, código, navegador…) e transmite o resultado de volta. Você nunca conecta ferramentas, modelos ou prompts manualmente — todos os outros campos abaixo são sobrescritas opcionais para quando quiser mais controle. Veja o Cookbook para exemplos prontos para copiar.

O POST retorna {"run_id", "trace_id"} — o run id é tudo o que você precisa para segui-lo. Uma desconexão do cliente nunca encerra o run; cobrança, persistência e a resposta final sempre chegam.

Obrigatório:

task — o que fazer, em linguagem natural (até 20.000 caracteres). Esse é o único campo que você deve enviar.

Opcional (todos têm padrões sensatos — sobrescreva apenas quando necessário):

model — vazio deixa a plataforma escolher um driver com capacidade para ferramentas. Fixe apenas para forçar um específico.
max_steps — teto de iterações de ferramenta/pensamento (1–50).
budget_usd — teto de custo rígido (> 0, até 100).
pro — desbloqueia raciocínio mais profundo e multithread (sub-agents paralelos em tarefas complexas).
project_id — executa com as instruções e arquivos de um project injetados como contexto.
conversation_id — encadeia este run sob uma conversa de chat existente (o resultado é escrito de volta nesse thread). Omita para uma tarefa autônoma.
skills — slugs de skills que o usuário escolheu explicitamente (até 8); vazio executa a linha de base pura (skills nunca são anexadas automaticamente).
persona_slug — um papel especialista da biblioteca agency-agents; injetado como um cabeçalho de identidade para este run. No máximo um.
history — turnos recentes ({role, content}, em que role é user ou assistant) para continuidade entre turnos. Ignorado quando conversation_id está definido (o histórico é então reconstruído no servidor).
mode — dica de faixa do compositor (auto deixa o roteador escolher entre chat / agent / cowork / code). Consultado apenas quando o roteador unificado está ativado.
approval_mode — postura para ações perigosas na máquina local: ask (padrão, pausa para o OK do usuário) ou auto (executa sem pausar).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Compare as tabelas de tarifas da Wise e da Airwallex; gere uma tabela.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

Acompanhar o run (Server-Sent Events)

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

acompanha o stream de eventos do run (text/event-stream). Cada frame é um objeto JSON em uma linha data:.

É seguro para reconexão: a linha id: carrega um id de entrada de stream, então o EventSource rastreia lastEventId nativamente e o reenvia como Last-Event-ID ao reconectar — um refresh, uma queda de WiFi ou um segundo dispositivo abrindo o run retoma exatamente de onde parou (o backlog é reproduzido a partir do último id visto). O gerador fecha após o frame terminal do run; períodos ociosos recebem um heartbeat : ping para que proxies não derrubem a conexão.

Tipos de evento type:

type	campos	quando
`step_start`	`step_no`	uma iteração de loop começou
`llm_delta`	`step_no`, `text`	texto do modelo transmitido
`reasoning` / `reasoning_delta`	`step_no`, `text`	a cadeia de pensamento do passo (completa ao fim do turno; deltas transmitem ao vivo)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	o modelo solicitou uma ferramenta (deltas transmitem os argumentos)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	uma ferramenta longa relata progresso intermediário
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	uma ferramenta terminou (pode trazer `artifacts`, `sources`, `screenshot_url`)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	uma ação local perigosa está aguardando (ou recebeu) uma decisão do usuário
`step_end`	`step_no`, `cost_usd`	iteração concluída
`context_compacted`	`step_no`, `summary`	turnos antigos foram compactados em um resumo para caber na janela de contexto
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	terminal — a resposta final está em `final_text`
`error`	`message`	falha terminal

Cada evento também carrega run_id (e step_no), então um consumidor multiplexado pode rotear frames sem estado por conexão. O stream termina com o frame terminal run_end (ou error) — não há sentinela [DONE].

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

Prefira GET …/attach a refazer o POST: ele é resumível a partir do Last-Event-ID, então clientes que reconectam nunca perdem frames. O run continua independentemente de alguém estar conectado ou não.

Gerenciar runs

GET/v1/workspaces/{workspace_id}/agent/runs —

lista runs (query: limit, project_id, scheduled_only, include_archived).

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

busca um: status, o final_text persistido, a trajetória completa de steps, custo e os artifacts produzidos.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

interrompe uma tarefa em execução. Cooperativo e entre workers (define um flag que o loop verifica no próximo limite de passo); idempotente — cancelar um run finalizado é uma no-op que retorna seu status terminal.

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

edita a entrada de recentes: title, archived, favorited, ou a move de project_id (um project_id nulo a remove).

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

exclui um run do histórico (seus passos são em cascata). Cancele um run em execução primeiro.

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

baixa todos os artifacts que o run produziu como um único .zip.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

cria / revoga um link público de somente leitura para replay (body: expires_in_days opcional).

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

responde a uma aprovação de ação local perigosa (body: {approved: true|false}), do tipo exibido por um evento approval_request.

Status do run

run_end.status (e GET …/runs/{run_id}) é um entre pending, running, succeeded, failed, cancelled, ou partial (a tarefa terminou com um resultado parcial ainda útil). Os estados terminais são succeeded, failed, cancelled e partial.

Arquivos que o agent produz (documentos, planilhas, slides, gráficos, web apps) voltam como artifacts no run. Um run é limitado tanto por budget_usd quanto pelo saldo do workspace, então nunca pode sair de controle.