VolundOS
Referência da APIExecução

Abrir uma conversa antes da primeira mensagem

Cria uma conversa vazia com o agente, parada (`status: "idle"`), e já começa a preparar a máquina dela enquanto a pessoa digita. Serve para o app que abre uma tela de conversa: a primeira resposta não paga o tempo de subir a máquina. O fluxo recomendado: 1. Ao abrir a tela, chame esta operação e guarde o `run_id`. 2. Para enviar cada mensagem, inclusive a primeira, use POST /v1/runs/{runId}/stream com esse `run_id`. 3. Se a pessoa voltar a digitar depois de mais de 10 minutos parada, chame POST /v1/runs/{runId}/prewarm antes de enviar: a máquina pode ter sido pausada nesse meio. A conversa recebe o título do corpo. Sem título, ela nasce como "Nova conversa" e passa a ter o começo da primeira mensagem como título. As recusas são as de POST /v1/agents/{agentId}/run. Exige o escopo runs:execute.

Atualizado em 04 de novembro de 2026
POST
/v1/agents/{agentId}/threads

Authorization

chaveDeApi
AuthorizationBearer <token>

Chave de API da organização, criada nas configurações. Envie-a em Authorization: Bearer <sua chave>.

In: header

Path Parameters

agentId*string

Id ou apelido do agente.

Header Parameters

Volund-Org?string

Slug (ou id) de uma organização cliente do parceiro dono da chave. Aceito só em GET /v1/agents, POST /v1/agents/{agentId}/run, POST /v1/agents/{agentId}/stream, POST /v1/agents/{agentId}/threads, POST /v1/runs/{runId}/continue, GET /v1/runs/{runId}, POST /v1/runs/{runId}/stream, POST /v1/runs/{runId}/stop, POST /v1/runs/{runId}/plan e POST /v1/runs/{runId}/prewarm, e só com o escopo partner:execute: a operação roda dentro da organização cliente, como a identidade de sistema dela, sobre as cópias gerenciadas dos agentes do parceiro. Qualquer outra rota responde 400 org_header_not_supported. Organização que não existe ou não é cliente deste parceiro: 404 client_not_found.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Corpo opcional. Sem corpo, a máquina é preparada e a conversa nasce como "Nova conversa", até receber o título da primeira mensagem.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/agents/string/threads" \  -H "Content-Type: application/json" \  -d '{}'
{  "run_id": "string",  "thread_id": "string",  "status": "idle",  "prewarm": "string",  "transcript_url": "string"}

Disparar um agente recebendo o passo a passo

Responde text/event-stream e emite os eventos à medida que o agente pensa, chama ferramentas e escreve. A preparação do run é idêntica à do disparo comum, inclusive `user` e `mcp`. Exige o escopo runs:execute.

Consultar um run

Devolve o estado do run e o passo a passo completo. Serve tanto para confirmar o resultado de um run assíncrono quanto para inspecionar as etapas intermediárias. A conversa de uma pessoa da aplicação (aberta com `user`) só é lida com o escopo app_users:read e pela chave ligada à mesma aplicação; com outra chave, a resposta é `run_not_found`. Exige o escopo runs:read.