Saltar para o conteúdo
Falnoa

Documentação

A API de agentes.Quatro chamadas.

O que um agente pode chamar, e os limites.

Fale connosco

Autenticação e erros

Todas as chamadas levam a chave de ingestão do agente como bearer token. Os erros têm o mesmo formato em toda a API.

{ "error": { "code": "invalid_request", "message": "send between 1 and 500 messages" } }

Enviar mensagens de uma conversa

POST /api/agent/v1/conversations/{conversation_id}/messages. O conversation_id é um identificador seu, de 1 a 200 caracteres. A resposta traz o id interno da conversa e quantas mensagens foram inseridas.

{
  "title": "Optional; defaults to the first user message",
  "user_ref": "optional end-user reference",
  "messages": [
    { "id": "m1", "role": "user", "content": "Where is my order?",
      "timestamp": "2026-01-02T10:00:00Z" },
    { "id": "m2", "role": "assistant", "content": "It ships tomorrow.", "latency_ms": 820,
      "usage": { "input_tokens": 1200, "output_tokens": 300, "cost": 0.0042, "model": "…" },
      "sources": [{ "title": "Shipping times", "excerpt": "…" }] }
  ]
}

Papéis

user, assistant, system ou tool. Só as mensagens assistant podem ser revistas.

Lote e repetições

Até 500 mensagens por chamada. Uma mensagem cujo id já foi guardado é ignorada, e o seu usage nunca conta duas vezes.

Usage

Opcional por mensagem: tokens de entrada e saída, custo em euros e modelo. Sem custo, é estimado pelos preços do orçamento do agente, se definidos.

Recusada com 409

Enquanto o agente não estiver aprovado no registo, ou quando tem um orçamento de bloqueio e o custo deste mês atingiu o limite.

Verificar a ligação

GET /api/agent/v1/ping devolve ok, o agente e uma lista de problemas. Uma chave errada ou rodada responde 401.

python -m blue_falnoa doctor https://YOUR-INSTANCE bfa_…
# or: curl -H "Authorization: Bearer bfa_…" https://YOUR-INSTANCE/api/agent/v1/ping

Pesquisar conhecimento publicado

GET /api/agent/v1/knowledge/search?q=prazo+de+devolucao&limit=5 devolve id do documento, título e excerto. Só a versão publicada de cada documento é pesquisável.

Agentes de fluxos de trabalho (A2A)

Para agentes A2A, o Blue Falnoa lê o cartão do agente, escolhe o protocolo 1.0 ou 0.3 e envia uma mensagem por passo do fluxo. Consulta a tarefa com espera crescente, ou aceita um callback em POST /api/agent/v1/step-runs/{step_run_id}/callback.

Uma tarefa completed passa a saídas do passo. input-required espera por uma pessoa, canceled cancela a execução e failed é um erro que uma pessoa pode repetir ou resolver à mão. Um passo à espera de um sistema externo é libertado com POST /api/agent/v1/step-runs/{step_run_id}/unlock.

Verificado apenas com os servidores de referência do SDK A2A oficial. Ainda não foi executado com um agente de terceiros em produção.

Todos os guias

Início rápido

Crie uma chave, envie uma mensagem e veja o agente ligado.

Gateway de ações

request_approval: pagar, enviar ou apagar só depois de uma pessoa aprovar.

SDK e adaptadores

Clientes Python e TypeScript, adaptadores OpenAI e LangChain, e n8n.

Verificação offline

Verifique um pacote de evidência offline com o bf-verify, ou no browser.

Documentação