Variáveis de Ambiente¶

Required¶

Variável	Descrição
`DATABASE_URL`	Conexão com banco de dados
`GOOGLE_CLOUD_PROJECT`	Projeto GCP
`MODEL`	Modelo LLM (padrão: `gemini-2.5-flash`)
`JWT_SECRET`	Segredo para validar JWTs

Feature Flags¶

Consulte Feature Flags para a lista completa.

Messaging¶

WhatsApp Official¶

Variável	Obrigatório	Descrição
`WHATSAPP_OFFICIAL_ACCESS_TOKEN`	Sim	Token de acesso da app Meta
`WHATSAPP_OFFICIAL_PHONE_ID`	Sim	Phone Number ID (obtido no Meta Business)
`WHATSAPP_OFFICIAL_VERIFY_TOKEN`	Sim	Verify token para webhook
`WHATSAPP_OFFICIAL_API_VERSION`	Não	Versão da API Meta (padrão: `v19.0`)
`WHATSAPP_OFFICIAL_APP_SECRET`	Não	App Secret para validação de webhook

WhatsApp Evolution¶

Variável	Obrigatório	Descrição
`WHATSAPP_EVOLUTION_BASE_URL`	Sim	URL base da API Evolution
`WHATSAPP_EVOLUTION_API_KEY`	Sim	API key da instância Evolution
`WHATSAPP_EVOLUTION_INSTANCE`	Sim	Nome da instância Evolution

Telegram¶

Variável	Obrigatório	Descrição
`TELEGRAM_BOT_TOKEN`	Sim	Token do bot Telegram

Slack¶

Variável	Obrigatório	Descrição
`SLACK_BOT_TOKEN`	Sim	Token do bot Slack (xoxb-...)
`SLACK_SIGNING_SECRET`	Sim	Signing secret para validação de requests
`SLACK_APP_ID`	Não	App ID do Slack (usado para identificar a app)

WebChat¶

Variável	Default	Descrição
`WEBCHAT_ENABLED`	—	Habilita canal WebChat (`true`/`1`)
`WEBCHAT_ALLOWED_ORIGINS`	`*`	Origens CORS permitidas (separadas por vírgula)
`WEBCHAT_WEBHOOK_PATH`	`/webchat/message`	Path do webhook
`WEBCHAT_ENABLE_CORS`	`true`	Habilita CORS

SSE (Server-Sent Events)¶

Variável	Default	Descrição
`SSE_ENABLED`	—	Habilita canal SSE (`true`/`1`)
`SSE_STREAM_TTL`	`300`	TTL do stream em segundos
`SSE_CLEANUP_INTERVAL`	`60`	Intervalo de limpeza de streams expirados
`SSE_MAX_EVENTS`	`1000`	Máximo de eventos por stream

Search¶

Duas tools de busca de produtos convivem no repositório — busca_produtos (BigQuery, em produção) e busca_produtos_qdrant (Qdrant, implementada mas ainda não conectada a nenhum agente — ver docs/search/QDRANT_PRODUCT_SEARCH.md).

`busca_produtos` (BigQuery — `ifriend_agent/tools/busca_produtos_tool.py`)¶

Variável	Default	Descrição
`GOOGLE_CLOUD_PROJECT`	`ifriend-platform`	Projeto GCP do dataset de produtos
`DATASET`	`Ifriend_produto`	Dataset BigQuery
`TABLE`	`mv_product_search_flat_embeddings`	Tabela materializada com embeddings (768D, modelo `mte002`)
`EMBEDDING_MODEL_NAME`	`mte002`	Modelo BQML (Vertex AI) usado por `ML.GENERATE_EMBEDDING`
`GEO_FILTER_THRESHOLD`	`0.30`	Threshold de distância cosseno para filtro geográfico (0.0 = mais restritivo, 1.0 = mais permissivo)

`busca_produtos_qdrant` (tool de consulta — `ifriend_agent/tools/busca_produtos_qdrant_tool.py`)¶

Variável	Default	Descrição
`QDRANT_URL` / `QDRANT_API_KEY`	—	mesma instância Qdrant compartilhada com a Knowledge Base
`PRODUCT_EMBEDDING_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	modelo `fastembed` usado para embeddar a query (`intfloat/multilingual-e5-small` foi removido do catálogo do fastembed) — precisa ser idêntico ao usado pelo job de sync (abaixo)
`PRODUCT_SEARCH_COLLECTION`	`products`	nome da collection no Qdrant (`stage_products` se `ENVIRONMENT=stage`)
`PRODUCT_SEARCH_TOP_K`	`10`	limite padrão de resultados
`PRODUCT_SEARCH_CACHE_TTL`	`600`	TTL (segundos) do cache em memória de embeddings de query
`ENVIRONMENT`	`production`	`stage` prefixa a collection (`stage_products`)

Sync CloudSQL → Qdrant (job — `runtime/workers/product_search_sync/`)¶

Cloud Run Job disparado por Cloud Scheduler (não um serviço HTTP) — lê a view mv_product_search_flat no CloudSQL, gera os embeddings localmente e sincroniza a collection products no Qdrant. Ver docs/search/QDRANT_PRODUCT_SEARCH.md para o design completo.

Variável	Default	Descrição
`CLOUDSQL_USER`	`agent-product-sync`	usuário MySQL dedicado a este job — mesma instância CloudSQL do serviço principal, mas não o mesmo usuário (`ifriend_agent`) nem o mesmo secret de senha
`CLOUDSQL_PASSWORD`	— (secret `trip-product-sync-db-pass`, mesmo valor em prod e stage)	senha do `agent-product-sync` — não confundir com `trip-ifriend-cloudsql-password[-stage]`, que é do usuário `ifriend_agent` do serviço principal
`CLOUDSQL_DATABASE`	`ifriend_v2`	banco onde vive a view `mv_product_search_flat`
`CLOUDSQL_UNIX_SOCKET`	—	socket da integração nativa Cloud Run ↔ Cloud SQL (`--set-cloudsql-instances`); se ausente, usa `CLOUDSQL_HOST`/`CLOUDSQL_PORT`
`QDRANT_URL` / `QDRANT_API_KEY`	—	mesma instância Qdrant compartilhada
`PRODUCT_EMBEDDING_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	precisa ser idêntico ao usado pela tool de consulta
`PRODUCT_SEARCH_COLLECTION`	`products`	idem à tool de consulta
`ENVIRONMENT`	`production`	`stage` prefixa a collection (`stage_products`) — precisa bater com o valor usado pela tool

Audio Transcription¶

Variável	Default	Descrição
`AUDIO_TRANSCRIPTION_MODEL`	`gemini-2.5-flash`	Modelo usado para transcrição de áudio
`AUDIO_MAX_BYTES`	`10485760`	Tamanho máximo de áudio em bytes (10 MB)

Support / Out-of-hours¶

Variável	Default	Descrição
`SUPPORT_START_HOUR`	—	Hora de início do atendimento (ex: `8`). Se não definido, desabilitado.
`SUPPORT_END_HOUR`	—	Hora de fim do atendimento (ex: `18`)
`SUPPORT_TIMEZONE`	`America/Sao_Paulo`	Fuso horário para cálculo de horário comercial
`SUPPORT_EMERGENCY_WHATSAPP`	`551152429559`	Número de WhatsApp para emergências fora do horário
`SUPPORT_OUT_OF_HOURS_MESSAGE`	Template padrão	Mensagem customizada para fora do horário (suporta `{start_hour}`, `{end_hour}`, `{emergency_whatsapp}`)

Agentforce (handoff Trip → SDR)¶

Ver Handoff Trip → Agentforce.

Variável	Default	Descrição
`ENABLE_AGENTFORCE_HANDOFF`	`false`	Liga o handoff via Agentforce
`AGENTFORCE_MY_DOMAIN_URL`	—	My Domain da org Salesforce (o token é pedido aqui, nunca em `login.salesforce.com`)
`AGENTFORCE_INSTANCE_ENDPOINT`	`instance_url` do OAuth	`instanceConfig.endpoint` da sessão
`AGENTFORCE_AGENT_ID`	—	ID `0Xx...` do agente SDR
`AGENTFORCE_CLIENT_ID`	—	Consumer Key do External Client App
`AGENTFORCE_CLIENT_SECRET`	—	Consumer Secret (Secret Manager)
`AGENTFORCE_TIMEOUT`	`60`	Timeout HTTP (s)
`AGENTFORCE_TOKEN_LIFETIME_MINUTES`	`20`	Cache do token (401 renova de qualquer forma)
`AGENTFORCE_IDLE_MINUTES`	`30`	Inatividade até encerrar a sessão e devolver ao Trip
`AGENTFORCE_CHANNELS`	`sse,webchat`	Canais (`message_metadata.source`) com handoff via Agentforce
`AGENTFORCE_ALLOW_WHITELABEL`	`false`	Whitelabel também escala ao SDR iFriend (padrão: WhatsApp do affiliate)
`AGENTFORCE_CASE_VARIABLE`	`Sales_Case_Payload`	Variável de contexto com o Case "Fluxo de Vendas" (corpo do Composite Upsert; vazio = não envia)
`AGENTFORCE_CASE_RECORD_TYPE_ID`	`012U4000001VcQDIA0`	RecordTypeId do Case "Fluxo de Vendas"
`AGENTFORCE_CONTEXT_VARIABLES`	—	JSON chave do Trip → API name da variável de contexto no agente

Session & Memory¶

Variável	Default	Descrição
`SESSION_TTL_MINUTES`	`60`	TTL de sessões em minutos
`MEMORY_TTL_DAYS`	`15`	TTL de memórias em dias (0 = sem expiração)
`MEMORY_SEARCH_LIMIT`	`5`	Máximo de resultados por busca de memória
`MEMORY_SUMMARY_MAX_CHARS`	`2000`	Máximo de caracteres no resumo LLM
`MEMORY_SUMMARY_MODEL`	`gemini-2.5-flash`	Modelo para sumarização de memórias

Loop Guard¶

Variável	Default	Descrição
`LOOP_GUARD_MAX_MESSAGES`	`5`	Mensagens por janela antes de abrir circuit breaker
`LOOP_GUARD_WINDOW_SECONDS`	`10`	Janela de tempo para detecção de burst
`LOOP_GUARD_COOLDOWN_SECONDS`	`30`	Duração do circuit breaker no estado OPEN
`LOOP_GUARD_MAX_TURNS_PER_SESSION`	`200`	Limite máximo de turnos por sessão
`LOOP_GUARD_REPEAT_THRESHOLD`	`3`	Mensagens repetidas para trigar circuit breaker
`LOOP_GUARD_REPEAT_WINDOW_SECONDS`	`60`	Janela para detecção de repetição textual

A2A Protocol¶

Variável	Default	Descrição
`ENABLE_A2A`	`false`	Habilita endpoint A2A
`ENABLE_A2A_STREAMING`	`false`	Habilita streaming SSE no A2A
`A2A_BASE_URL`	—	URL pública para o AgentCard
`A2A_REQUIRED_ROLE`	`ROLE_A2A_USER`	Role JWT obrigatória para acesso A2A
`A2A_TASK_TTL_HOURS`	`24`	TTL de tasks persistidas

Affiliate & Whitelabel¶

Variável	Descrição
`PARTNER_CODE`	Código do parceiro/afiliado (injetado via JWT `custom_claims`)
`WHITELABEL_BASE_URL`	URL base do whitelabel para consulta de branding

Knowledge Base (FAQ por Affiliate)¶

Ver Affiliate → Knowledge Base para o mecanismo completo.

Consulta (`ifriend_agent`/`unified_bot.py`)¶

Variável	Default	Descrição
`ENABLE_KNOWLEDGE_BASE`	`false`	Habilita `knowledge_base_agent` globalmente (kill-switch)
`QDRANT_URL`	—	URL da instância Qdrant (infra compartilhada, já roda no GKE do time)
`QDRANT_API_KEY`	—	API key do Qdrant
`KB_EMBEDDING_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	Modelo `fastembed` usado para gerar o embedding da pergunta (`intfloat/multilingual-e5-small` foi removido do catálogo do fastembed) — precisa ser idêntico ao usado na indexação pelo Knowledge Base Service (ver abaixo)
`KB_TOP_K`	`3`	Número de chunks retornados pela busca
`KB_SIMILARITY_THRESHOLD`	`0.75`	Score mínimo do melhor resultado para considerar relevante; abaixo disso, cai para `faq_agent` genérico
`KB_CACHE_TTL`	`600`	TTL (segundos) do cache em memória de embeddings/resultados de busca

Ingestão — API (`apps/knowledge-base-service/`)¶

Variável	Default	Descrição
`QDRANT_URL` / `QDRANT_API_KEY`	—	mesma instância Qdrant compartilhada com a consulta
`JWT_PUBLIC_KEY`	—	valida o JWT do affiliate (mesmo secret usado pelo `unified_bot.py`)
`JWT_ALGORITHM`	`RS256`	algoritmo do JWT
`STORAGE_BUCKET`	`ifriend-ia-agents`	bucket GCS onde os documentos brutos são gravados
`PUBSUB_TOPIC`	`kb-indexing-jobs` (`kb-indexing-jobs-stage` em stage)	tópico Pub/Sub que dispara o worker de indexação
`KB_MAX_UPLOAD_BYTES`	`20971520` (20MB)	tamanho máximo de upload aceito
`ENVIRONMENT`	`production`	`stage` prefixa `STORAGE_PREFIX` (`kb-uploads-stage/`) e a collection do Firestore (`kb_jobs_stage`) e do Qdrant (`stage_affiliate_<id>_kb`) — ver Isolamento por ambiente

Ingestão — Worker (`runtime/workers/knowledge_base/`)¶

Variável	Default	Descrição
`QDRANT_URL` / `QDRANT_API_KEY`	—	mesma instância Qdrant compartilhada
`KB_EMBEDDING_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	precisa ser idêntico ao usado na consulta — modelos diferentes geram vetores incomparáveis
`IFRIEND_API_KB_WRITEBACK_ENABLED`	`false`	kill-switch do write-back de `knowledgeBaseCollection` na iFriend API — habilitar só depois de confirmar o endpoint em cada ambiente
`IFRIEND_API_BASE_URL`	`https://api.theifriend.com` (`https://stage.api.theifriend.com` em stage)	host da iFriend API para o `PATCH /affiliates/{id}/root_agent`
`IFRIEND_API_EMAIL`	`mcp@theifriend.com`	conta sistêmica para autenticação (mesma usada pelo agente principal)
`IFRIEND_API_PASSWORD`	— (secret)	senha da conta sistêmica — mesmo secret `trip-ifriend-api-password` já usado pelo `cloudbuild.yaml` principal
`ENVIRONMENT`	`production`	`stage` prefixa a collection do Qdrant (`stage_affiliate_<id>_kb`) e do Firestore (`kb_jobs_stage`) — precisa bater com o valor usado pela API

Logging¶

Variável	Default	Descrição
`LOG_LEVEL`	`INFO`	Nível de logging (DEBUG, INFO, WARNING, ERROR)
`DEBUG`	`false`	Modo debug
`ENABLE_TRACING`	`false`	Habilita Google Cloud Trace

Cloud Build¶

See cloudbuild.yaml and cloudbuild.stage.yaml for deploy-specific overrides.