Decidir o plano de um run
Aprova ou reprova o plano que um turno com `plan_mode: true` propôs. O `request_id` é o do evento `awaiting_input` com `kind: "plan"`, ou o de `pending_plan` em GET /v1/runs/{runId}. Aprovar grava a decisão, desliga o modo de plano e retoma a conversa para executar o plano, em segundo plano; o desfecho sai em GET /v1/runs/{runId}. O turno que propôs o plano precisa ter terminado: enquanto ele termina, a decisão responde 409 `turn_still_running` sem gravar nada, e quem chama tenta de novo em alguns segundos. Reprovar grava a recusa com a `note` e devolve a conversa ociosa, sem retomar o agente: o replanejamento é um turno novo de quem chamou, por POST /v1/runs/{runId}/continue ou /stream com `plan_mode: true` e a nota como `input`. Decide quem é aprovador do pedido ou quem configura o agente, avaliado como a pessoa dona da chave. Exige o escopo runs:execute.
Authorization
chaveDeApi Chave de API da organização, criada nas configurações. Envie-a em Authorization: Bearer <sua chave>.
In: header
Path Parameters
Identificador do run. É o mesmo da conversa: um run continua na mesma thread.
Header Parameters
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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/runs/string/plan" \ -H "Content-Type: application/json" \ -d '{ "request_id": "string", "decision": "approve" }'{ "run_id": "string", "request_id": "string", "decision": "approved", "resumed": true}Preparar a máquina de uma conversa
Sobe ou retoma a máquina da conversa e prepara o que o agente usa, em segundo plano, para a próxima mensagem não esperar por isso. Responde na hora; o trabalho continua depois da resposta e nenhum erro dele afeta a conversa. Use quando a pessoa volta a digitar numa conversa parada há mais de 10 minutos, antes de enviar a mensagem por POST /v1/runs/{runId}/stream. Conversa antiga sem máquina ativa não ganha máquina nova (`no_warm_session`); conversa com turno em andamento não precisa (`run_in_progress`). Exige o escopo runs:execute.
Parar o turno de um run
Para o turno em andamento, como o botão de parar da conversa. O turno vivo no sandbox é parado, inclusive o que espera aprovação ou pergunta, em alguns segundos, e a conversa ganha a mensagem "Execução interrompida pelo usuário.". Depois disso, `GET /v1/runs/{runId}` responde `failed`. Idempotente: com o turno já terminado, ou a conversa esperando o cofre, responde `stopped: false`. Só para o turno com execução registrada no sandbox. Turno em andamento sem ela recebe 409 `run_not_stoppable`: o run síncrono, o de `callback_url` e o de canal conduzido pelo servidor não são interrompidos de fora. Um run de `/stream` ou `async: true` também recebe o 409 nos primeiros segundos, antes de registrar a execução; repetir o pedido logo depois para ele. Exige o escopo runs:execute.