REST API

Crie e gerencie agentes de IA

Uma API, todos os LLMs. Configure um agente (provider + modelo + prompt + schema) e execute-o com uma chamada HTTP — sem acoplar seu codigo a um provedor de IA especifico.

Comecar em 3 passos → Ver referencia completa

Autenticacao

Toda chamada exige o header X-API-Key com a sua chave pessoal. Cada chave da acesso apenas aos recursos do seu proprio usuario.

curl https://ai.bfholding.capital/api/agents \
  -H "X-API-Key: SUA_CHAVE_AQUI"

🔑

Header obrigatorio: X-API-Key. Veja, copie e rotacione a sua chave em Dashboard → API Keys. Pegar minha chave →

Base URL

Todos os endpoints deste guia sao relativos a esta base. Os caminhos comecam com /api/agents.

https://ai.bfholding.capital

Quickstart

Do zero a uma resposta do agente em tres passos. Escolha a sua linguagem.

# 1. Crie um agente
curl -X POST https://ai.bfholding.capital/api/agents \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistente de Suporte",
    "provider_id": "_global_openai",
    "model": "gpt-5.2",
    "system_prompt": "Voce e um assistente de suporte cordial."
  }'

# 2. Execute o agente  (use o id retornado acima)
curl -X POST https://ai.bfholding.capital/api/agents/AGENT_ID/execute \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Ola!"}]}'

# 3. Liste e gerencie
curl https://ai.bfholding.capital/api/agents -H "X-API-Key: SUA_CHAVE"

import requests

BASE = "https://ai.bfholding.capital"
HEADERS = {"X-API-Key": "SUA_CHAVE"}

# 1. Crie um agente
agent = requests.post(f"{BASE}/api/agents", headers=HEADERS, json={
    "name": "Assistente de Suporte",
    "provider_id": "_global_openai",
    "model": "gpt-5.2",
    "system_prompt": "Voce e um assistente de suporte cordial.",
}).json()["agent"]

# 2. Execute o agente
resp = requests.post(
    f"{BASE}/api/agents/{agent['id']}/execute",
    headers=HEADERS,
    json={"messages": [{"role": "user", "content": "Ola!"}]},
).json()
print(resp["response"]["content"])

# 3. Liste e gerencie
print(requests.get(f"{BASE}/api/agents", headers=HEADERS).json())

const BASE = "https://ai.bfholding.capital";
const HEADERS = { "X-API-Key": "SUA_CHAVE", "Content-Type": "application/json" };

// 1. Crie um agente
const created = await fetch(`${BASE}/api/agents`, {
  method: "POST", headers: HEADERS,
  body: JSON.stringify({
    name: "Assistente de Suporte",
    provider_id: "_global_openai",
    model: "gpt-5.2",
    system_prompt: "Voce e um assistente de suporte cordial.",
  }),
}).then(r => r.json());

// 2. Execute o agente
const out = await fetch(`${BASE}/api/agents/${created.agent.id}/execute`, {
  method: "POST", headers: HEADERS,
  body: JSON.stringify({ messages: [{ role: "user", content: "Ola!" }] }),
}).then(r => r.json());
console.log(out.response.content);

Criar e gerenciar agentes

O CRUD completo do recurso central da plataforma. Todos os endpoints exigem X-API-Key.

GET /api/agents Lista os seus agentes com paginacao e filtros por status, pasta e tags. ▸

Parametros

Campo	Tipo	Descricao
page	int	Numero da pagina (comeca em 1).
per_page	int	Itens por pagina (1 a 100).
status	string	Filtra por active ou inactive.
folder_id	string	Filtra por pasta (root = sem pasta).
tags	string	Tags separadas por virgula; retorna quem tem todas.

Resposta

{ "items": [ { "id": "665f…", "name": "Assistente de Suporte", "slug": "assistente-de-suporte", "status": "active", … } ],
  "total": 1, "page": 1, "per_page": 20, "pages": 1 }

▶ Testar no console

POST /api/agents Cria um novo agente. So o name e obrigatorio; informe provider + modelo para deixa-lo pronto para executar. ▸

Apenas name (3 a 200 caracteres) e obrigatorio; todo o resto tem defaults sensatos. Informe provider_id + model para o agente ja sair executavel. Envie so os campos que quiser mudar.

Identidade

Campo	Tipo	Obrig.	Descricao
name	string	sim	Nome do agente (>= 3 caracteres).
description	string	nao	Texto livre para organizacao interna (nao afeta o comportamento). Default vazio.
tags	string[]	nao	Lista de rotulos para filtrar em GET /api/agents?tags=... (retorna quem tem todas).
folder_id	string	nao	Pasta para organizar no dashboard. Use "root" para a raiz.

Modelo e provider

Campo	Tipo	Obrig.	Descricao
provider_id	string	nao	Provider global (_global_openai...) ou id de provider proprio.
model	string	nao	Modelo do LLM (ex.: gpt-5.2, claude-opus-4-8).

Comportamento

Campo	Tipo	Obrig.	Descricao
system_prompt	string	nao	Instrucao de sistema que define o comportamento.
response_schema	object	nao	Schema JSON para forcar saida estruturada (opcional).

Config de geracao (objeto config)

config e um objeto opcional com estas sub-chaves:

Campo	Tipo	Obrig.	Descricao
config.temperature	float	nao	Criatividade da resposta, 0 a 2. Default 0.7. Ignorado por modelos de reasoning (o3, gpt-5.x).
config.max_tokens	int	nao	Maximo de tokens na resposta. Default 4096; limitado ao teto do modelo.
config.top_p	float	nao	Nucleus sampling (alternativa a temperature), 0 a 1. Opcional.
config.reasoning_effort	string	nao	Esforco de reasoning: low \| medium \| high \| xhigh. So para modelos de reasoning.

Recursos vinculados (RAG, tools, MCP)

Campo	Tipo	Obrig.	Descricao
integration_ids	string[]	nao	IDs de integracoes (tools em Python) que o agente pode chamar. IDs inacessiveis sao descartados.
knowledge_base_ids	string[]	nao	IDs de bases de conhecimento (RAG) injetadas como contexto. IDs inacessiveis sao descartados.
mcp_server_ids	string[]	nao	IDs de servidores MCP externos cujas tools o agente pode usar.

Fallback de modelo

Campo	Tipo	Obrig.	Descricao
fallback_enabled	bool	nao	Liga o fallback automatico de modelo em erro do provider. Default true (provider/modelo sugeridos se nao informados).
fallback_provider_id	string	nao	Provider de fallback. Se vazio com fallback ligado, e sugerido automaticamente.
fallback_model	string	nao	Modelo de fallback. Sugerido automaticamente se vazio.

Publicacao (chat publico e widget)

Campo	Tipo	Obrig.	Descricao
public_chat_enabled	bool	nao	Publica uma pagina de chat sem login em /chat/{slug}. As execucoes consomem o seu saldo. Default false.
public_chat_rate_limit	int	nao	Limite de mensagens por hora por IP no chat publico, 1 a 1000. Default 20.
widget_enabled	bool	nao	Habilita o widget embutivel (iframe). Ajuste a aparencia com os campos widget_* (ver referencia OpenAPI).

Limite de custo

Campo	Tipo	Obrig.	Descricao
usage_limit_enabled	bool	nao	Liga um teto de custo mensal por agente. Default false.
usage_limit_monthly	float	nao	Teto de custo mensal em USD (0 = sem limite). Excedido -> 429.

Requisicao

{
  "name": "Assistente de Suporte",
  "description": "Tira duvidas de produto em pt-BR",
  "provider_id": "_global_openai",
  "model": "gpt-5.2",
  "system_prompt": "Voce e um assistente de suporte cordial e conciso.",
  "config": { "temperature": 0.5, "max_tokens": 2048 },
  "response_schema": null,
  "knowledge_base_ids": ["665f…kb"],
  "integration_ids": ["665f…tool"],
  "fallback_enabled": true,
  "public_chat_enabled": true,
  "public_chat_rate_limit": 30,
  "usage_limit_enabled": true,
  "usage_limit_monthly": 10.0,
  "tags": ["suporte", "pt-br"]
}

▶ Testar no console

GET /api/agents/{id} Retorna a configuracao completa de um agente pelo id. ▸

Resposta

{ "id": "665f…", "name": "Assistente de Suporte", "slug": "assistente-de-suporte",
  "provider_id": "_global_openai", "model": "gpt-5.2", "status": "active",
  "fallback_enabled": true, "integration_ids": [], "knowledge_base_ids": [], … }

▶ Testar no console

PUT /api/agents/{id} Atualiza um agente. Envie apenas os campos que quer mudar (patch parcial). ▸

Requisicao

{ "system_prompt": "Nova instrucao de sistema.", "config": { "temperature": 0.3 } }

▶ Testar no console

DELETE /api/agents/{id} Remove um agente permanentemente. ▸

Resposta

{ "success": true }

▶ Testar no console

GET /api/agents/{id}/monthly-cost Retorna o custo (USD) consumido pelo agente no mes corrente. ▸

Resposta

{ "success": true, "data": { "cost": 1.2345, "month": "2026-07" } }

▶ Testar no console

Executar agentes

Rode o agente de forma sincrona, em streaming (SSE) ou com midia. O custo e debitado do dono do agente.

POST /api/agents/{id}/execute Executa o agente e devolve a resposta completa (bloqueante). ▸

Corpo

Campo	Tipo	Obrig.	Descricao
messages	array	sim	Mensagens da conversa: [{role, content}]. Obrigatorio.
session_id	string	nao	Mantem o contexto entre chamadas. Nova sessao se omitido.

Resposta

{ "success": true, "session_id": "sess_abc123",
  "response": { "content": "Ola! Posso ajudar…", "tokens_used": { "total": 60 } },
  "cost": 0.00021, "files": [] }

▶ Testar no console

POST /api/agents/{id}/execute-stream Executa o agente transmitindo a resposta em tempo real via SSE. ▸

SSE

event: start
data: {"session_id": "sess_abc123"}

event: chunk
data: {"content": "Ola"}

event: usage
data: {"tokens_used": {"total": 60}, "cost": 0.00021}

event: done
data: {"execution_id": "665f…"}

POST /api/agents/{id}/execute-media Executa o agente a partir de uma imagem, audio ou documento. ▸

multipart/form-data

curl -X POST https://ai.bfholding.capital/api/agents/AGENT_ID/execute-media \
  -H "X-API-Key: SUA_CHAVE" \
  -F "file=@audio.mp3" \
  -F "message=Resuma este audio"

Console de teste

Cole a sua chave, escolha um endpoint e rode a chamada de verdade — sem sair desta pagina. As chamadas usam a sua base URL e sao feitas do seu navegador.

Sua X-API-Key

A chave fica apenas neste navegador (nunca e enviada aos nossos servidores de log). · Lembrar neste navegador

Base URL

Endpoint

Caminho

Corpo da requisicao (JSON)

—

A resposta aparece aqui.

Codigos de resposta

A plataforma responde sucesso como { "success": true, ... } e erros como { "detail": "mensagem" }.

Codigo	Significado
200	OK — requisicao bem-sucedida.
400	Requisicao invalida (ex.: agente sem provider configurado).
401	X-API-Key ausente ou invalida.
403	Sem permissao — o recurso pertence a outro usuario.
404	Recurso nao encontrado.
422	Erro de validacao do corpo (ex.: name com menos de 3 caracteres).
429	Limite de custo/uso atingido (agente, usuario ou plataforma).

Proximos passos

Referencia completa (Swagger) → Todos os endpoints da plataforma com try-it-out interativo. Streaming (SSE) → Receba tokens ao vivo com /execute-stream. Abrir o Dashboard → Crie agentes pela interface e pegue a sua API Key.