Provedores e modelos

O Hub é multi-provider. Cada agente referencia um modelo no formato provider/model_id e o LangGraph resolve a chamada via langchain.chat_models.init_chat_model. A lista de provedores realmente disponíveis em runtime depende das chaves de API presentes no ambiente da aplicação web.

Provedores suportados

Cinco provedores são reconhecidos pelo resolver de modelos. O endpoint GET /api/models filtra a lista pelas variáveis de ambiente presentes no pod web — provedores sem chave configurada não aparecem no seletor.

O identificador final de modelo persistido no campo configurable.model segue o padrão provider/model_id, por exemplo openai/gpt-4o-mini (default), anthropic/claude-3-5-sonnet-latest ou openrouter/anthropic/claude-3.5-sonnet. O model_id pode conter barras adicionais — o parser usa apenas o primeiro / para separar provider do resto.

Como escolher modelo no UI

O seletor de modelo aparece no painel de configuração de cada agente sempre que o schema do grafo expõe um campo com x_oap_ui_config.type = "model_selector". No agente padrão o campo é model e o default é openai/gpt-4o-mini.

Override via Langfuse

Quando o agente tem langfuse_prompt_name definido, o config do prompt no Langfuse (chaves provider, model, temperatura, reasoning_effort) sobrescreve a configuração do UI. Isso permite trocar modelo sem redeploy:

{
  "provider": "anthropic",
  "model": "claude-3-5-sonnet-latest",
  "temperatura": 0.3,
  "reasoning_effort": "medium"
}

Se model já vier prefixado (openai/gpt-4o), o provider é ignorado para evitar duplicação (openai/openai/gpt-4o).

Fallback automático

O Hub não faz failover automático entre provedores em runtime. Se a chamada ao provedor configurado falha, a exceção propaga para o nó call_model do grafo e a execução é marcada como erro (rastreado em Langfuse e GlitchTip).

O único fallback implementado é no carregamento do prompt: se o Langfuse estiver indisponível durante o fetch de langfuse_prompt_name, o agente continua com o system_prompt e modelo configurados no assistant.config.configurable e emite a métrica langfuse_unavailable.

Estratégias recomendadas para resiliência:

• OpenRouter como provider único — o próprio OpenRouter roteia entre upstreams e oferece fallback interno por modelo.
• Múltiplos agentes com modelos distintos, escolhidos por regra de negócio antes da invocação.
• Monitorar erros via GlitchTip e configurar alertas para o nó call_model (rate de erros por agente).

Custos e quotas

Custos são responsabilidade do provedor — o Hub não impõe quota própria por organização.

Rastreio de uso. Toda chamada ao modelo é instrumentada com Langfuse no compile do grafo, o que captura prompt_tokens, completion_tokens, total_tokens e custo calculado por modelo. Para inspecionar consumo:

• Projeto Langfuse: Simplafy-Hub
• Filtros típicos: por agent_id, por org_id (tags), por modelo
• Métricas de fallback são emitidas como langfuse_unavailable no Prometheus do cluster

Quotas e limites. Os limites são os do provedor (rate limits de OpenAI/Anthropic, créditos de OpenRouter/xAI, cota de ZhipuAI). Excessos retornam erro 429 do upstream, que aparece como falha do nó call_model.

Adicionar credenciais

As chaves de API dos provedores de LLM não ficam em Credential ou CredentialSet por organização — elas são variáveis de ambiente globais do pod web (simplafy-hub-web) e do pod LangGraph (simplafy-hub-langgraph). Isso significa que todos os agentes da plataforma compartilham as mesmas chaves.

# Listar chaves atuais (via skill infisical)
infisical secrets list --path=/web --env=prd

# Adicionar/atualizar uma chave
infisical secrets set OPENAI_API_KEY=sk-... --path=/web --env=prd
infisical secrets set OPENAI_API_KEY=sk-... --path=/langgraph --env=prd

infisical secrets set ANTHROPIC_API_KEY=sk-ant-... --path=/web --env=staging
infisical secrets set ANTHROPIC_API_KEY=sk-ant-... --path=/langgraph --env=staging

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
XAI_API_KEY=xai-...
ZHIPU_API_KEY=...
ZHIPU_API_BASE=https://open.bigmodel.cn/api/paas/v4

Verificar provedores ativos

Após configurar uma nova chave, confirme que ela apareceu no UI:

curl https://hub.simplafy.com.br/api/models

Resposta esperada (apenas providers com chave válida):

{
  "providers": [
    { "id": "openai", "name": "OpenAI" },
    { "id": "anthropic", "name": "Anthropic" },
    { "id": "zhipu", "name": "ZhipuAI (GLM)" }
  ]
}

Se o provider esperado não aparece, verifique se a chave foi propagada para o pod correto (tanto web quanto langgraph precisam dela — o web filtra a UI, o langgraph executa a chamada).