BYOK — chave especifica por agente
Como atribuir uma chave OpenAI ou Anthropic dedicada a um agente especifico para segmentar custos entre clientes ou marcas.
O UltronChat permite que cada agente tenha sua propria chave BYOK, sobrescrevendo a chave global. Util quando:
- Voce gerencia multiplas marcas e quer separar custos no dashboard do provider.
- Voce atende clientes de uma agencia e quer cobrar o consumo de cada um separadamente.
- Voce quer isolar risco — se uma chave e comprometida ou atinge limite, so um agente e afetado.
Resolucao hibrida
Quando o agente precisa chamar o LLM, o UltronChat resolve a chave em 2 niveis:
- Chave especifica do agente (
agents.encrypted_api_key), se existir — tem prioridade. - Se nao houver, usa a chave global do usuario (
user_api_keys) para o provider do agente.
Se nenhuma das duas existir, o agente e bloqueado na ativacao (trigger trg_enforce_byok_on_agents).
Cadastrar chave especifica
- Va para o agente em
/dashboard/[connectionId]/agent. - Role ate a secao Avancado / Chave de API.
- Escolha entre:
- Usar chave global (padrao) — o agente usa sua chave global.
- Usar chave especifica deste agente — digite a chave OpenAI ou Anthropic para este agente.
- Se escolheu especifica, cole a chave (
sk-...ousk-ant-...). - Clique em Validar e salvar.
O UltronChat:
- Valida a chave via probe no provider (
POST /user-keys/validate). - Confirma que o provider da chave bate com o
llm_providerdo agente (ex.: nao aceita chave OpenAI em agente configurado como Anthropic). - Criptografa e grava em
agents.encrypted_api_key. - Mostra fingerprint da chave especifica no form.
Screenshot: form do agente com "Chave especifica: sk-...a3f2" ativa.
Remover a chave especifica
No mesmo form, clique em Voltar para chave global. O UltronChat limpa agents.encrypted_api_key. Dali em diante o agente volta a usar a chave global.
Se nao houver chave global nem especifica apos remover, o agente e automaticamente pausado.
Regras e restricoes
- Provider da chave deve bater com o do agente — se o agente esta em OpenAI, so chave OpenAI serve.
- Mudar provider do agente resetа a chave especifica — voce precisa cadastrar de novo.
- Chave invalida pausa o agente — assim como no caso de chave global. O erro e gravado em
agents.api_key_last_error.
Dashboard de custos segmentado
Para ter custos separados por agente/marca no provider:
- OpenAI — crie projects no platform.openai.com, gere uma chave por project e associe ao agente correspondente.
- Anthropic — crie workspaces ou keys nomeadas em console.anthropic.com.
Depois de um mes, o dashboard do provider mostra consumo detalhado por project/workspace, que casa 1:1 com agentes do UltronChat.
Comparativo — global vs especifica
| Aspecto | Global | Especifica |
|---|---|---|
| Cadastro | 1 vez em /dashboard/settings/api-keys | 1 vez por agente |
| Quantas chaves voce precisa | 1 por provider | 1 por agente |
| Separacao de custos | Nao | Sim |
| Simplicidade | Maior | Menor |
| Gerenciamento em escala | Complicado com muitos agentes | Ideal para >3 agentes |
Recomendacao: comece com global. Se um dia voce tiver 2+ marcas e quiser ver custo separado, migre para especifica.