Referência de Configuração

Todas as chaves de configuração e variáveis de ambiente, e a forma como a fonte ativa é escolhida

Como a configuração é carregada

A configuração é um simples dicionário carregado por uma ConfigSource (consulte agent_lab/core/config.py) e associado ao container de DI. create_app() seleciona uma fonte através de default_config_source(), exatamente por esta ordem — a primeira correspondência prevalece:

#	Condição (variável de ambiente definida)	Fonte ativa
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — Vault através do token projetado da ServiceAccount do pod
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(nenhuma das anteriores)	`VaultConfigSource` — lê `VAULT_URL` / `VAULT_TOKEN`

É possível substituir a seleção por aplicação:

app = create_app(config_source=YamlConfigSource("config.yml"))  # explicit

Chaves de configuração

O dicionário que a fonte ativa tem de devolver. Os valores apresentados provêm de config-dev.yml (desenvolvimento); a aplicação de referência inclui config-dev.yml, config-test.yml e config-docker.yml exatamente com esta estrutura.

Chave	Finalidade	Valor de exemplo
`api_base_url`	URL base pública desta API (utilizado nas ligações das respostas)	`http://localhost:8000`
`cdp_url`	Endpoint do Chrome headless (CDP) para agentes web (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Monta o middleware de autenticação e as rotas `/auth` quando `true`	`false`
`auth.url`	URL base do Keycloak	`https://auth.example.com`
`auth.realm`	Nome do realm do Keycloak	`agent-lab`
`auth.client_id`	ID do cliente OIDC	`agent-lab-api`
`auth.client_secret`	Segredo do cliente OIDC	`…`
`broker.url`	URL do Redis para atualizações de estado pub/sub em operações longas	`redis://localhost:6379/0`
`db.url`	PostgreSQL — dados relacionais	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL — base de dados de embeddings pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL — base de dados de checkpoints do LangGraph (memória do agente)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Endereço do Vault (também reescrito para que os serviços possam ler segredos)	`http://localhost:8200`
`vault.token`	Token do Vault	`dev-only-token`
`static.enabled`	Servir um build de SPA (`false` quando não existe build de frontend)	`false`
`static.directory`	Diretório que contém o build da SPA	`static/frontend/browser`
`static.index_file`	Ficheiro de fallback da SPA	`index.html`
`static.mount_path`	Ponto de montagem da SPA	`/`

static é um caso especial: as fontes YAML configuram-no explicitamente, enquanto a fonte Vault o deriva de uma convenção no código — fica ativado quando existe um build de SPA em STATIC_DIR.

Payload de segredos do Vault

A VaultConfigSource lê um único segredo KV-v2 (engine secret, caminho app_secrets por predefinição) e mapeia-o para as chaves acima:

Chave do segredo	Corresponde a
`api_base_url`	`api_base_url`
`cdp_url`	`cdp_url`
`auth_enabled` → `auth.enabled`	`auth.enabled`
`auth_url` → `auth.url`	`auth.url`
`auth_realm` → `auth.realm`	`auth.realm`
`auth_client_id` → `auth.client_id`	`auth.client_id`
`auth_client_secret` → `auth.client_id`	`auth.client_secret`
`broker_url`	`broker.url`
`db_url`	`db.url`
`db_vectors`	`db.vectors`
`db_checkpoints`	`db.checkpoints`

A forma de aprovisionar esse payload (Docker Compose de desenvolvimento, Kubernetes, Terraform) é descrita em Segredos com Vault e no guia de deployment.

Variáveis de ambiente

Seleção da fonte de configuração

Variável	Predefinição	Finalidade
`DEVELOPING`	(não definida)	Seleciona `config-dev.yml` (depuração no IDE)
`TESTING`	(não definida)	Seleciona `config-test.yml` (suite de testes)
`DOCKER`	(não definida)	Seleciona `config-docker.yml` (Compose)
`VAULT_URL`	(não definida)	Endereço do Vault para a fonte predefinida
`VAULT_TOKEN`	(não definida)	Token do Vault para a fonte predefinida
`VAULT_ENGINE_PATH`	`secret`	Ponto de montagem KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	Caminho do segredo
`VAULT_K8S_ROLE`	(não definida)	Role de autenticação Kubernetes do Vault; ativa a fonte K8s e tem precedência
`STATIC_DIR`	`static/frontend/browser`	Onde o build da SPA é procurado

Observabilidade

Variável	Predefinição	Finalidade
`OTEL_EXPORTER_OTLP_ENDPOINT`	(não definida — tracing desativado)	URL base do collector OTLP/HTTP; traces → `/v1/traces`, métricas → `/v1/metrics`, registos → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Nome do recurso OTel
`SERVICE_VERSION`	`snapshot`	Versão do recurso OTel
`LANGFUSE_HOST`	(não definida)	URL base do Langfuse; juntamente com as duas chaves abaixo, ativa o backend Langfuse
`LANGFUSE_PUBLIC_KEY`	(não definida)	Chave `pk-lf-…` do Langfuse
`LANGFUSE_SECRET_KEY`	(não definida)	Chave `sk-lf-…` do Langfuse
`LANGWATCH_ENDPOINT`	(não definida)	Endpoint do LangWatch; juntamente com a chave abaixo, ativa o backend LangWatch
`LANGWATCH_API_KEY`	(não definida)	Chave de API do LangWatch

Se faltar alguma variável do Langfuse, o backend Langfuse é desativado silenciosamente e a aplicação continua a arrancar (o mesmo acontece com o LangWatch). Detalhes e ponto de extensão: Observabilidade.

Autenticação e integrações

Variável	Predefinição	Finalidade
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(não definida)	Credenciais do Microsoft Entra ID para `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(não definida)	Serviço de embeddings utilizado pelos agentes de recuperação
`OPENAI_API_KEY`	(não definida)	OpenAI (entrada de áudio dos memorandos de voz; juiz de simulação predefinido)

Simulações (apenas suite de testes)

Variável	Predefinição	Finalidade
`SIMULATION_LLM_MODEL`	(obrigatória)	Tag do modelo que executa os agentes em teste (por exemplo, `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(obrigatória)	Endpoint compatível com OpenAI que serve esse modelo
`SIMULATION_LLM_API_KEY`	`dummy-key`	Chave de API do endpoint, se necessária
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	ID do modelo litellm utilizado pelo LLM-as-judge
`SIMULATION_JUDGE_API_BASE`	predefinição do fornecedor	Endpoint personalizado compatível com OpenAI para o juiz
`SIMULATION_JUDGE_API_KEY`	predefinição do fornecedor	Chave de API do endpoint personalizado do juiz

Consulte Testes e Simulações para saber como são consumidas.

Fontes de configuração personalizadas

Implemente a ABC ConfigSource e passe-a a create_app(config_source=...) — útil para AWS Secrets Manager, deployments apenas com variáveis de ambiente ou para envolver outra fonte:

from agent_lab import ConfigSource, create_app


class MyConfigSource(ConfigSource):
    def load(self) -> dict:
        return {
            "api_base_url": "https://api.example.com",
            "db": {"url": "postgresql://…", "vectors": "…", "checkpoints": "…"},
            "auth": {"enabled": True, "url": "…", "realm": "…", "client_id": "…", "client_secret": "…"},
            "broker": {"url": "redis://…"},
            # … remaining keys as in the table above
        }


app = create_app(config_source=MyConfigSource())

As fontes incluídas (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) e default_config_source() são todas exportadas a partir do pacote de topo agent_lab.