API
Além do Studio, agentes podem ser acionados e acompanhados por HTTP. Esta página cobre o que interessa a quem integra.
Duas formas de autenticar
| Forma | Para quê | Como |
|---|---|---|
| Sessão do Imaginne | Scripts que agem como uma pessoa | A mesma sessão do Imaginne, no cabeçalho de autorização |
| Credencial de endereço | Sistemas que acionam um agente específico | A credencial gerada ao criar o endereço HTTP |
Não existe cadastro nem login próprios do Agents. Quem entra no Imaginne entra aqui.
A credencial de endereço é a opção certa para integração: ela vale para um agente, tem limites próprios e não dá acesso ao Studio.
Acionar por endereço HTTP
Chame o endereço criado, com a credencial e o corpo no formato que o agente declara.
A resposta é imediata e não é o resultado:
{
"execution_id": "exec_…",
"status": "queued",
"status_url": "…"
}
O fluxo nunca roda dentro da requisição. Uma automação que espera aprovação humana não caberia num tempo de resposta HTTP.
Entrada validada
O disparo por endereço valida a entrada contra o que o agente declara. Campo obrigatório ausente, tipo incorreto ou valor fora das opções são recusados sem criar execução.
Idempotência
Envie uma chave de idempotência para tornar seguro repetir a requisição depois de um tempo esgotado na rede:
- mesma chave, mesmo corpo → devolve a execução original;
- mesma chave, corpo diferente → recusado.
A chave não contorna limites de frequência.
Respostas possíveis
| Situação | O que significa |
|---|---|
| Aceito | A execução foi criada |
| Repetição de chave | A execução original é devolvida |
| Entrada recusada | Os dados não batem com o que o agente declara |
| Não autorizado | Credencial errada ou endereço inexistente — a mesma resposta para os dois |
| Não existe mais | O endereço expirou ou foi revogado |
| Grande demais | O corpo passou do limite |
| Limite atingido | Frequência ou simultaneidade do endereço |
A resposta idêntica para credencial errada e endereço inexistente é deliberada: não há como descobrir identificadores válidos por tentativa.
Acompanhar uma execução
Com o identificador da execução você pode:
| Ação | Uso |
|---|---|
| Consultar o estado | Saber se concluiu, falhou ou está aguardando |
| Ler a linha do tempo | Os eventos, em ordem, com retomada por cursor |
| Cancelar | Cancelamento cooperativo, verificado entre etapas |
| Repetir | Cria uma execução nova a partir da mesma versão |
A linha do tempo registra estado semântico. Ela não expõe raciocínio interno do modelo nem contagem de tokens.
Acionar como pessoa
Com a sessão do Imaginne, um script pode acionar um agente manualmente, informando o ambiente e a entrada. Vale o mesmo limite de frequência da execução manual pelo Studio.
Formato das respostas
Sucesso e erro têm envelopes distintos e estáveis. Erros trazem um código estável — o texto pode evoluir, o código não — e, quando aplicável, a lista de campos com problema.
Isolamento
Todo recurso pertence a uma organização, derivada da credencial. Um recurso de outra organização responde como inexistente, e não como "sem permissão".
Obter o contrato
O contrato completo, na versão da sua instalação, é fornecido pela equipe que administra a plataforma.
Próximos passos
Esta página ajudou?
Reportar um problema nesta páginaNão envie senhas, chaves, tokens ou dados de clientes.