Criar e gerenciar via API

CRUD completo de agents por REST: crie o workflow por JSON, edite o rascunho, liste, remova — tudo com a mesma API key.

Atualizado em 10 de ago. de 2026

Tudo o que o builder faz, a API faz: um POST com o JSON do workflow cria o agent, um PATCH edita o rascunho, e o publish promove a versão que roda em produção. Os agents criados por API aparecem normalmente no builder (e vice-versa) — é um só ciclo, com duas interfaces.

O escopo vem da sua API key: os agents pertencem à organização e ao projeto dela, e uma key de outro projeto recebe 404.

Nada inválido entra

Todo workflow enviado passa pelo validador do runtime (o mesmo motor que executa) antes de ser salvo. Workflow que não funcionaria responde 422 com o relatório de erros — nó por nó. Ver Validar, sandbox e publicar.

Os endpoints

Método	Endpoint	O que faz
POST	`/v1/agents`	Cria um agent (rascunho). Workflow é validado.
GET	`/v1/agents`	Lista os agents do escopo da key (`limit`/`offset`).
GET	`/v1/agents/{id}`	Detalhe com o workflow do rascunho.
PATCH	`/v1/agents/{id}`	Edição parcial do rascunho. Workflow é validado.
DELETE	`/v1/agents/{id}`	Remove o agent (a versão publicada sai do ar).
POST	`/v1/agents/validate`	Valida um workflow sem salvar nada.
POST	`/v1/agents/{id}/publish`	Promove o rascunho a versão publicada.

Criar

POSThttps://agents.hinow.ai/v1/agentsBearer hi_SUA_API_KEY

Cria um agent como rascunho. Só name é obrigatório — dá para criar vazio e mandar o workflow depois num PATCH.

Parâmetros

namestring· bodyobrigatório
Nome do agent (2–255 caracteres).
descriptionstring· body
Descrição livre.
workflowobject· body
O grafo `{nodes, edges}` — o mesmo formato do builder. Validado antes de salvar; inválido responde `422`.
modelstring· body
Modelo padrão do agent (fallback para nós de agente sem modelo próprio).
system_promptstring· body
Prompt padrão (fallback, como no builder).
configobject· body
Configurações extras (temperatura etc.), como no builder.

Respostas

201Agent criado como rascunho.

{
  "agent": {
    "id": "ddfe14bd-4bfb-4d6a-83a0-4e907278ad10",
    "name": "Pesquisador Web",
    "status": "draft",
    "published_version": 0,
    "has_unpublished_changes": false,
    "workflow": {"nodes": [/* ... */], "edges": [/* ... */]},
    "created_at": "2026-08-10T10:23:45Z"
  }
}

400`name` ausente/curto demais, ou workflow que não é um objeto.

422O workflow não passou no validador — nada foi salvo.

{
  "error": {"message": "workflow failed validation", "type": "validation_error"},
  "validation": {
    "valid": false,
    "errors": [{"code": "missing_start", "message": "workflow needs exactly one 'start' node"}],
    "warnings": []
  }
}

O JSON do workflow

É o mesmo formato que o builder salva: nodes (cada um com id, type, data e position) e edges ligando os ids. Três detalhes que valem por quase todos os erros de iniciante:

Um nó start, e o fluxo segue pelas edges até um nó end.
Ferramentas não entram no fluxo: um nó de ferramenta (busca, webhook, MCP...) conecta no slot do agente — targetHandle: "slot-1" — e não numa edge comum.
Ferramentas se encadeiam com sourceHandle: "output": uma edge de ferramenta para ferramenta forma um pipeline (ex.: busca → síntese, onde o resultado da busca é resumido antes de voltar ao agente).

A referência completa de cada tipo de nó e seus campos é a mesma do builder: Cards do builder.

workflow mínimo com busca na webjson

{
  "name": "Pesquisador Web",
  "workflow": {
    "nodes": [
      { "id": "start",    "type": "start",      "data": { "label": "Início", "variables": [] } },
      { "id": "agent-1",  "type": "agent",      "data": { "name": "Pesquisador",
          "model": "hinow/himax",
          "system_prompt": "Você é um assistente de pesquisa. Use a busca na web para fatos atuais." } },
      { "id": "search-1", "type": "web_search", "data": { "config": { "num_results": 5 } } },
      { "id": "end-1",    "type": "end",        "data": { "label": "Fim", "status": "success" } }
    ],
    "edges": [
      { "id": "e1", "source": "start",    "target": "agent-1" },
      { "id": "e2", "source": "search-1", "target": "agent-1", "targetHandle": "slot-1" },
      { "id": "e3", "source": "agent-1",  "target": "end-1" }
    ]
  }
}

Busca com síntese

Para o agente receber um resumo em vez da lista crua de resultados, encadeie a síntese na busca: adicione um nó summarize e a edge {"source": "search-1", "sourceHandle": "output", "target": "summarize-1"}. O pipeline roda a cada busca, na mesma cobrança do run.

Listar, ler, editar, remover

curl https://agents.hinow.ai/v1/agents?limit=20 \
  -H "Authorization: Bearer hi_SUA_API_KEY"
# → {"agents": [{"id": "...", "name": "...", "status": "draft"}], "total": 3}

curl https://agents.hinow.ai/v1/agents/SEU_AGENT_ID \
  -H "Authorization: Bearer hi_SUA_API_KEY"
# → {"agent": {..., "workflow": {"nodes": [...], "edges": [...]}}}

# PATCH parcial: só os campos enviados mudam. Editar o workflow
# altera apenas o RASCUNHO — a versão publicada segue no ar.
curl -X PATCH https://agents.hinow.ai/v1/agents/SEU_AGENT_ID \
  -H "Authorization: Bearer hi_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Nova descrição", "workflow": {"nodes": [/*...*/], "edges": [/*...*/]}}'

curl -X DELETE https://agents.hinow.ai/v1/agents/SEU_AGENT_ID \
  -H "Authorization: Bearer hi_SUA_API_KEY"
# → {"deleted": true, "id": "..."}
# A versão publicada sai do ar na hora (o /run passa a responder 404).

O objeto agent

Campo	Significado
`status`	`draft` (nunca publicado) ou `published` (tem versão no ar).
`published_version`	Contador de publicações — `0` enquanto rascunho.
`has_unpublished_changes`	`true` quando o rascunho divergiu da versão publicada: hora de [testar em sandbox e publicar](/pt/api/agents/publish).
`workflow`	O grafo do rascunho (o publicado roda no `/run`).

Fluxo recomendado

Crie → valide → rode o rascunho com version: "draft" → publique → execute. Cada passo tem endpoint próprio; nada vai ao ar sem você mandar.

Esta página foi útil?