Validar, sandbox e publicar
O validador do runtime recusa o que não roda; o sandbox executa o rascunho de verdade; o publish promove a versão que vai ao ar.
Atualizado em 10 de ago. de 2026
Entre criar e ir para produção existem três degraus — todos por API:
- Validar: o workflow é checado pelo próprio runtime (grafo, campos de cada nó, modelos no catálogo).
- Sandbox: o rascunho roda de verdade, com
"version": "draft"no/run— sem tocar a versão publicada. - Publicar: o rascunho válido vira a versão que o
/run, o widget e o A2A servem.
https://agents.hinow.ai/v1/agents/validateBearer hi_SUA_API_KEYValida um workflow avulso (dry-run). Nada é criado nem alterado — ideal para CI ou para validar enquanto o usuário edita.
Parâmetros
workflowobject· bodyobrigatórioO grafo `{nodes, edges}` a validar.
Respostas
{
"valid": false,
"errors": [
{"code": "missing_start", "message": "workflow needs exactly one 'start' node"},
{"code": "unknown_model", "message": "model 'gpt-4-fake' not found in the catalog (see GET https://api.hinow.ai/v1/models)"}
],
"warnings": [
{"code": "missing_end", "message": "no 'end' node: the run finishes at the first node without outgoing edges"}
]
}Erros impedem salvar e publicar; warnings não bloqueiam — apontam comportamento provavelmente não intencional (nó inalcançável, ferramenta sem slot, if sem ramo false). Cada item traz um code estável, a mensagem e, quando faz sentido, o node_id.
| Alguns codes de erro | Causa |
|---|---|
missing_start / multiple_start | O fluxo precisa de exatamente um nó start. |
unknown_node_type | Tipo de nó que o runtime não conhece — a lista completa está em Cards do builder. |
edge_source_missing / edge_target_missing | Edge apontando para um id que não existe em nodes. |
tool_needs_slot / flow_into_tool | Ferramenta ligada como se fosse fluxo — ela conecta no targetHandle: "slot-N" do agente. |
if_no_condition / while_no_condition | Nó de controle sem a condição que o move. |
participants_missing | Debate/votação/sequencial sem participantes (estáticos, dinâmicos ou conectados). |
unknown_model | Slug de modelo fora do catálogo — confira em GET https://api.hinow.ai/v1/models. |
O mesmo /run de sempre, com um campo a mais. O rascunho executa de verdade — mesmas ferramentas, mesmos eventos, cobrança normal por inferência — mas a versão publicada continua intocada servindo produção.
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": "teste do rascunho", "version": "draft", "stream": false}'O sandbox valida o rascunho na hora: se ele foi quebrado depois (por exemplo, editando no builder), o /run com version: "draft" responde 422 com o relatório — em vez de executar algo que falharia no meio.
https://agents.hinow.ai/v1/agents/{agent_id}/publishBearer hi_SUA_API_KEYRevalida o rascunho e o promove a versão publicada. A troca é atômica: runs em andamento terminam na versão antiga; os próximos já pegam a nova.
Parâmetros
agent_iduuid· pathobrigatórioO agent a publicar.
Respostas
{
"agent": {
"id": "ddfe14bd-4bfb-4d6a-83a0-4e907278ad10",
"name": "Pesquisador Web",
"status": "published",
"published_version": 2,
"published_at": "2026-08-10T10:24:13Z",
"has_unpublished_changes": false
}
}Depois de publicado, o rascunho continua livre: edite à vontade (has_unpublished_changes fica true), teste em sandbox e publique de novo quando estiver pronto. Produção só muda no publish.