Pular para o conteúdo
Menu da documentação

Produtos

Agents

Execute agentes, prompts e fluxos publicados pela API, acompanhe a execução e entenda como funciona a aprovação humana.

#Executar um agente

Com o escopo "Executar agentes", a chave inicia a versão publicada de um agente do workspace. A chamada devolve na hora o identificador da execução (202); o agente roda em seguida.

bash
curl -sS -X POST "https://aiuby.com/api/platform/agents/$AGENTE_ID/runs" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{"input":"Pedido 4471: conferir e encaminhar","idempotencyKey":"pedido-4471"}'
  • input: o pedido, com até 100.000 caracteres.
  • idempotencyKey: obrigatório. Repetir a chamada com a mesma chave não cria outra execução.
  • project: opcional, para separar o custo por projeto.

#Acompanhar a execução

bash
curl -sS "https://aiuby.com/api/platform/agents/runs/$EXECUCAO_ID" \
  -H "Authorization: Bearer $AIUBY_TOKEN"

Uma chave só consulta as execuções que ela mesma iniciou.

#Aprovação humana

Quando o agente chega a uma ação com efeito, a execução para e espera. Uma pessoa com permissão vê o texto exato da ação na área do cliente e aprova ou recusa.

  • A aprovação vence em 24 horas.
  • Nenhuma chave de API aprova: só uma pessoa, pela tela.
  • Uma ferramenta bloqueada pelo Guard é recusada mesmo depois de aprovada.

Aviso de conclusão

É possível receber um aviso quando a execução termina. O aviso vem assinado no cabeçalho x-aiuby-signature, no formato v1= seguido do HMAC-SHA256 do carimbo de tempo e do corpo, calculado com o segredo combinado. Confira a assinatura antes de confiar no conteúdo.

#Prompts

Com o escopo "Executar prompts", a chave lê o formulário de um prompt publicado e o executa com os valores das variáveis.

bash
curl -sS "https://aiuby.com/api/platform/prompts/$PROMPT_ID" -H "Authorization: Bearer $AIUBY_TOKEN"

curl -sS -X POST "https://aiuby.com/api/platform/prompts/$PROMPT_ID/runs" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{"values":{"cliente":"<nome do cliente>","tom":"consultivo"},"idempotencyKey":"proposta-001"}'

#Fluxos

Com o escopo "Executar fluxos", a chave inicia um fluxo publicado que aceite o gatilho por API. Se o fluxo não tiver esse gatilho publicado, a resposta é 409 trigger_not_allowed.

bash
curl -sS -X POST "https://aiuby.com/api/platform/flows/$FLUXO_ID/runs" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{"input":"Pedido 4471: conferir e encaminhar","idempotencyKey":"pedido-4471"}'

curl -sS "https://aiuby.com/api/platform/flows/runs/$EXECUCAO_ID" -H "Authorization: Bearer $AIUBY_TOKEN"

A entrada de um fluxo tem até 20.000 caracteres. Agentes dentro do fluxo rodam em nome da chave, e a aprovação humana continua esperando uma pessoa.

#Limites

O quêLimite
Inícios de execução30 por minuto
Consultas de execução120 por minuto
Execuções de agente abertas ao mesmo tempo20 por chave

Limite

Agentes não têm acesso a shell de produção. O dono ou um administrador liga o n8n e os servidores MCP da empresa em cada workspace: não há servidor MCP público da AIUBY.