first_contas/README.md

Agent Contas FIRST migrado para Agent Framework OCI

Este projeto é uma versão executável do Agent Contas FIRST migrada para o padrão do Agent Framework OCI. Ele implementa um agente de atendimento para dúvidas e operações de contas/faturas de telecom, mantendo a lógica específica do domínio de contas em uma camada fina e delegando workflow, roteamento, guardrails, judges, memória, RAG, MCP, cache e observabilidade para o framework corporativo.

Observação de segurança: o arquivo .env.example do pacote contém exemplos de valores sensíveis. Este README explica os parâmetros, mas não reproduz senhas, tokens, chaves privadas nem secrets. Para uso real, mantenha esses valores fora do Git e injete por vault, secret manager, variável de ambiente segura ou arquivo .env local não versionado.

O que é este projeto

O pacote contém quatro partes principais:

Parte	Caminho	Função
Backend do agente	app/	API FastAPI que expõe /gateway/message, normaliza canal, resolve identidade, executa o workflow LangGraph e chama o Agent Contas.
Configurações do framework	config/ e llm_profiles.yaml	YAMLs de agente, roteamento, guardrails, judges, identity, MCP servers, tools e mapeamento de parâmetros.
MCP Server legado TIM/FIRST	mcp_servers/legacy_tim_mcp/	Adaptador HTTP MCP que expõe tools no contrato esperado pelo framework e chama APIs TIM/FIRST ou mock.
Mock de serviços externos	backend_mock/	Servidor FastAPI que simula endpoints TIM/FIRST como fatura, contrato, VAS, PDF, protocolo, contestação, status, SMS e tracking.

O projeto também mantém legacy_reference/ apenas como referência de rastreabilidade do legado. A decisão de migração foi não portar a camada própria de workflow/guardrails/judges/RAG do legado, evitando duplicidade com o Agent Framework OCI.

O que é o Agente de Contas

O Agente de Contas é um agente especializado no domínio telecom_contas. Ele atende perguntas e fluxos relacionados a fatura, pagamento, segunda via, contestação, plano, serviços adicionais, protocolos e SMS. No código, a lógica específica fica principalmente em:

• app/agents/contas_agent.py: comportamento de domínio, prompt do agente, seleção declarativa de tools por intent e montagem de contexto com RAG/MCP.
• config/routing.yaml: intents suportadas e tools relacionadas.
• config/tools.yaml: catálogo das tools MCP disponíveis.
• config/mcp_parameter_mapping.yaml: mapeamento das chaves canônicas de negócio para argumentos reais das APIs TIM/FIRST.
• config/identity.yaml: resolução de identidade e aliases, como msisdn, invoice_id, asset_id, ura_call_id e session_id.

Funcionalidades prometidas pelo agente

Atendimento de faturas e contas

• Explicar fatura, valor, vencimento, status e itens cobrados.
• Consultar fatura completa via consultar_fatura.
• Consultar pagamentos e baixa via consultar_pagamentos.
• Ajudar em dúvidas sobre cobrança proporcional, divergência de valor e histórico de cobrança.

Segunda via e PDF

• Recuperar dados da fatura atual.
• Recuperar PDF ou segunda via quando disponível via recuperar_pdf_fatura.
• Preparar envio de informações de boleto/código por canal, quando a política permitir.

Contestação e protocolo

• Identificar intenção de contestar cobrança.
• Consultar evidências antes de orientar o cliente.
• Abrir contestação via abrir_contestacao, marcada como ação sensível e com confirmação requerida.
• Registrar protocolo via registrar_protocolo.
• Consultar status de protocolo/SR via consultar_status_sr.
• Atualizar status de SR via atualizar_status_sr, também como ação sensível.

Plano, serviços e VAS

• Consultar plano/contrato ativo via consultar_plano.
• Listar serviços ativos, VAS/SVA, bundles e benefícios via listar_servicos.
• Orientar cancelamento ou bloqueio de VAS.
• Executar cancelar_vas e bloquear_vas apenas como ações com confirmação explícita.

SMS e tracking operacional

• Enviar SMS via enviar_sms, com confirmação.
• Registrar tracking/activity via registrar_tracking.

Segurança, qualidade e observabilidade

• Guardrails de entrada e saída configuráveis por YAML.
• Judges de qualidade, groundedness, sentimento e tom.
• Output Supervisor com retry.
• Eventos IC/NOC/GRL e telemetria Langfuse/OTEL.
• Cache MCP para consultas.
• Memória conversacional e summary memory.

Como ele funciona com o Agent Framework OCI

A arquitetura de execução é:

Frontend / curl / canal
        ↓
FastAPI backend: POST /gateway/message
        ↓
ChannelGateway do Agent Framework OCI
        ↓
IdentityResolver + BusinessContext
        ↓
SessionRepository + Memory + Summary Memory
        ↓
Workflow LangGraph do template
        ↓
Input Guardrails
        ↓
Enterprise Router / routing.yaml
        ↓
ContasAgent / AgentRuntimeMixin
        ↓
RAG nativo + MCPToolRouter nativo
        ↓
legacy_tim_mcp
        ↓
APIs TIM/FIRST reais ou backend_mock
        ↓
LLM + Output Supervisor + Output Guardrails + Judges
        ↓
Resposta final + telemetria + persistência

O backend inicializa os componentes nativos em app/main.py:

• ChannelGateway para normalizar mensagens de web/voz/WhatsApp/texto.
• IdentityResolver para transformar msisdn, invoice_id, asset_id, ura_call_id etc. em BusinessContext canônico.
• AgentProfileRegistry para carregar o agente contas_first.
• create_llm, create_memory, create_conversation_summary_memory, create_session_repository, create_checkpoint_repository, create_cache e create_usage_repository.
• create_mcp_tool_router para carregar config/mcp_servers.yaml, config/tools.yaml e config/mcp_parameter_mapping.yaml.
• AgentWorkflow para executar o pipeline LangGraph corporativo.

Integração com o framework

O projeto usa o Agent Framework OCI nos seguintes pontos:

Recurso do framework	Como é usado no projeto
LangGraph workflow	app/workflows/agent_graph.py orquestra o pipeline corporativo.
AgentRuntimeMixin	ContasAgent herda de AgentRuntimeMixin para usar RAG, MCP, memória, cache e montagem de prompt.
Enterprise Router	config/routing.yaml define intents, prioridades, keywords, exemplos e tools por intent.
Guardrails	config/guardrails.yaml ativa MSK/VLOOP na entrada e REVPREC/PINJ/DLEX_OUT na saída.
Judges	config/judges.yaml define response_quality, groundedness, sentiment e tone.
Output Supervisor	Controlado por ENABLE_OUTPUT_SUPERVISOR e OUTPUT_SUPERVISOR_MAX_RETRIES.
IdentityResolver	config/identity.yaml converte aliases de canal/legado em chaves canônicas.
BusinessContext	Chaves customer_key, contract_key, interaction_key, account_key, resource_key, session_key acompanham todo o fluxo.
MCPToolRouter	Executa tools declaradas em config/tools.yaml no servidor legacy_tim.
MCP Parameter Mapping	config/mcp_parameter_mapping.yaml converte chaves canônicas em argumentos como msisdn, invoice_id, customer_id, asset_id.
Cache MCP	Queries têm cache configurado por tool em config/tools.yaml.
RAG	Usa o RAG nativo do framework, com namespace contas_first na metadata do agente.
Memória	Usa histórico e summary memory do framework.
Observabilidade	Usa Telemetry, Langfuse, IC/NOC/GRL e analytics publisher.
SSE	SSEHub permite eventos de fluxo quando o endpoint SSE estiver em uso.

Customizações específicas do Contas

As customizações de domínio são intencionais e concentradas:

1. Intents de contas em config/routing.yaml:

   • billing_invoice_explanation
   • billing_payment_status
   • billing_second_copy
   • billing_contestation
   • service_plan_information
   • vas_services_information
   • generic_billing_rag
   • billing_protocol_status
   • billing_protocol_register
   • vas_cancel_or_block
   • send_billing_sms
   • tracking_activity

2. Tools de telecom em config/tools.yaml:

   • consultas com cache: consultar_fatura, consultar_pagamentos, consultar_plano, listar_servicos, recuperar_pdf_fatura, consultar_status_sr;
   • ações sem cache e com confirmação quando sensíveis: registrar_protocolo, abrir_contestacao, atualizar_status_sr, cancelar_vas, bloquear_vas, enviar_sms, registrar_tracking.

3. MCP Server legado em mcp_servers/legacy_tim_mcp/main.py, que adapta endpoints TIM/FIRST ao contrato MCP:

GET  /mcp/tools/list
POST /mcp/tools/call

4. Mock de backend externo em backend_mock/app.py, útil para testar o MCP sem depender das APIs reais.

5. Prompt específico do agente, em ContasAgent.run(), instruindo o modelo a não inventar dados de fatura, pagamento, plano, VAS, protocolo ou contestação e a usar resultados MCP/RAG como evidência.

Tecnologias utilizadas

• Python 3.11/3.12 recomendado.
• FastAPI e Uvicorn.
• Pydantic e pydantic-settings.
• LangGraph e LangChain Core.
• Agent Framework OCI.
• OCI Generative AI / OCI SDK.
• Oracle Autonomous Database / oracledb, quando usado para persistência/RAG.
• Redis, opcional para cache distribuído.
• Langfuse, opcional para traces.
• OpenTelemetry, opcional para exportação OTEL.
• HTTPX para chamadas HTTP do MCP legado.
• YAML para configuração declarativa.
• Docker Compose opcional.

Requisitos para subir a aplicação

Obrigatórios

• Python 3.11 ou 3.12.
• pip e venv.
• Agent Framework OCI instalado no mesmo ambiente Python do backend.
• Portas livres:
  • 8000: backend do agente;
  • 5173: frontend;
  • 8100: MCP Server legado;
  • 8001: mock das APIs externas.

Para execução real com OCI/ADB

• Acesso ao OCI Generative AI ou endpoint OCI configurado.
• OCI_CONFIG_FILE, OCI_PROFILE, OCI_REGION, OCI_COMPARTMENT_ID e modelo/endpoint válidos.
• Acesso ao Autonomous Database se VECTOR_STORE_PROVIDER=autonomous ou repositórios forem configurados para ADB.
• Wallet/DSN/senha conforme o modo de conexão.

Para observabilidade

• Langfuse local ou remoto se ENABLE_LANGFUSE=true.
• Redis se ENABLE_REDIS_CACHE=true.
• OTEL collector se ENABLE_OTEL=true.

Instalação inicial

No diretório raiz do projeto:

cd first_contas
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Instale o framework no mesmo ambiente. Exemplo em modo editable:

pip install -e "../agent_framework"

Ajuste o caminho para o local real do seu agent_framework_oci.

Configuração recomendada para teste local com mock externo

Para testar o fluxo completo com backend + MCP + mock server, deixe o MCP chamando o mock HTTP local. No .env do backend e no .env do MCP, ajuste endpoints para localhost:8001:

TIM_MCP_USE_MOCK=false
TIM_COMPLETE_INVOICES_URL=http://localhost:8001/customers/v1/completeInvoices
TIM_PROFILE_BILL_URL=http://localhost:8001/customers/v1/completeInvoices/profile
TIM_CONTRATO_URL=http://localhost:8001/access/v1/contractInformation
TIM_QUERY_VAS_URL=http://localhost:8001/access/v1/productsSingleVas
TIM_CANCEL_VAS_URL=http://localhost:8001/access/v1/singleVas
TIM_BLOCK_VAS_URL=http://localhost:8001/customers/v1/createPartialBlocking
TIM_BILL_PDF_URL=http://localhost:8001/invoices/v1/invoiceRecover
TIM_PROTOCOL_URL=http://localhost:8001/customers/v1/backOfficeSRopening
TIM_CUSTOMER_CONTESTATION_URL=http://localhost:8001/interactions/v1/customerContestation
TIM_SERVICE_REQUEST_STATUS_URL=http://localhost:8001/interactions/v1/statusServiceRequest
TIM_SMS_URL=http://localhost:8001/customers/v1/smsSend
TIM_TRACKING_ACTIVITIES_URL=http://localhost:8001/customers/v1/trackingActivities

Também é possível usar TIM_MCP_USE_MOCK=true; nesse modo o MCP usa mock interno e não precisa do backend_mock. Como você pediu a subida dos quatro terminais, o modo recomendado acima mantém o backend_mock participando do fluxo.

Como abrir os 4 terminais para subir a aplicação toda

Terminal 1 — MCP Server legado TIM/FIRST

cd first_contas
./scripts/start_legacy_tim_mcp.sh

Alternativa manual:

cd first_contas/mcp_servers/legacy_tim_mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --host 0.0.0.0 --port 8100 --reload

Teste:

curl -s http://localhost:8100/health | python -m json.tool
curl -s http://localhost:8100/mcp/tools/list | python -m json.tool

Terminal 2 — Mock server das APIs externas

cd first_contas/backend_mock
python -m venv .venv
source .venv/bin/activate
pip install fastapi 'uvicorn[standard]'
uvicorn app:app --host 0.0.0.0 --port 8001 --reload

Teste:

curl -s http://localhost:8001/health | python -m json.tool

Terminal 3 — Backend do agente

cd first_contas
./scripts/start_backend.sh

Alternativa manual:

cd first_contas
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Teste:

curl -s http://localhost:8000/health | python -m json.tool
curl -s http://localhost:8000/debug/mcp/call/consultar_fatura   -H 'Content-Type: application/json'   -d '{"business_context":{"customer_key":"11999999999","contract_key":"FAT-2026-06","account_key":"CUST-001","interaction_key":"URA-001"}}' | python -m json.tool

Terminal 4 — Frontend

Este pacote não traz o código do frontend. Use o frontend do agent_framework_oci ou o projeto de frontend que você já usa com o backend do framework. Exemplo:

cd "/agent_framework_oci/agent_frontend"
npm install
npm run dev -- --host 0.0.0.0 --port 5173

No frontend, configure a URL do backend como:

http://localhost:8000

E use agent_id:

contas_first

Payload mínimo esperado pelo backend:

{
  "channel": "web",
  "tenant_id": "default",
  "agent_id": "contas_first",
  "payload": {
    "text": "Quero entender por que minha fatura veio mais alta",
    "session_id": "sess-contas-001",
    "user_id": "11999999999",
    "customer_key": "11999999999",
    "contract_key": "FAT-2026-06",
    "account_key": "CUST-001",
    "interaction_key": "URA-001",
    "channel": "web"
  }
}

Testes por curl incluídos no pacote

Depois de subir os serviços:

cd first_contas
./tests/curl_mcp_health.sh
./tests/curl_mcp_consultar_fatura.sh
./tests/curl_backend_health.sh
./tests/curl_backend_debug_mcp.sh
./tests/curl_gateway_fatura.sh

Endpoints principais

Endpoint	Serviço	Descrição
GET /health	Backend	Health check do backend do agente.
POST /gateway/message	Backend	Entrada principal de mensagens normalizadas ou payloads de canal.
POST /debug/mcp/call/{tool}	Backend	Diagnóstico direto de chamada MCP com business_context.
GET /health	MCP	Health check do MCP legado.
GET /mcp/tools/list	MCP	Lista tools disponíveis no servidor MCP.
POST /mcp/tools/call	MCP	Executa uma tool MCP.
GET /health	Mock	Health check do backend mock.

BusinessContext e mapeamento MCP

O framework trabalha com chaves canônicas:

{
  "customer_key": "11999999999",
  "contract_key": "FAT-2026-06",
  "account_key": "CUST-001",
  "interaction_key": "URA-001",
  "resource_key": "ASSET-001",
  "session_key": "sess-contas-001"
}

O MCPToolRouter converte essas chaves para os parâmetros reais de cada tool. Exemplos:

Tool	Mapeamento principal
consultar_fatura	customer_key → msisdn, contract_key → invoice_id, account_key → customer_id, interaction_key → ura_call_id, session_key → session_id
consultar_pagamentos	customer_key → msisdn, account_key → customer_id, interaction_key → ura_call_id
consultar_plano	customer_key → msisdn, resource_key → asset_id, account_key → customer_id
listar_servicos	customer_key → msisdn, resource_key → asset_id
abrir_contestacao	customer_key → msisdn, contract_key → invoice_id, account_key → customer_id
cancelar_vas/bloquear_vas	customer_key → msisdn, resource_key → app_id

Arquivos mais importantes

Arquivo	Descrição
README.md	README original do pacote, com visão geral da migração.
README_MIGRACAO_CONTAS_FIRST.md	Decisões de migração e rastreabilidade.
.env.example	Exemplo de configuração completa.
app/main.py	Bootstrap FastAPI e inicialização dos componentes do framework.
app/agents/contas_agent.py	Agente específico de Contas.
app/agents/runtime.py	Mixin/apoio runtime do agente.
app/workflows/agent_graph.py	Workflow LangGraph corporativo.
config/agents.yaml	Registro do agente contas_first.
config/routing.yaml	Intents, priorities, keywords e tools por intent.
config/tools.yaml	Catálogo declarativo de tools MCP.
config/mcp_servers.yaml	Servidor MCP legacy_tim em http://localhost:8100/mcp.
config/mcp_parameter_mapping.yaml	Mapeamento BusinessContext -> args das tools.
config/identity.yaml	Resolução de aliases de identidade.
config/guardrails.yaml	Guardrails globais.
config/judges.yaml	Judges globais.
mcp_servers/legacy_tim_mcp/main.py	Servidor MCP legado adaptador TIM/FIRST.
backend_mock/app.py	Mock de endpoints externos TIM/FIRST.
scripts/start_backend.sh	Script para subir backend.
scripts/start_legacy_tim_mcp.sh	Script para subir MCP legado.
tests/*.sh	Curls de validação.

Docker Compose opcional

O pacote inclui docker-compose.yml com dois serviços:

• legacy-tim-mcp, porta 8100;
• agent-contas, porta 8000.

Execução:

cd first_contas
cp .env.example .env
cp mcp_servers/legacy_tim_mcp/.env.example mcp_servers/legacy_tim_mcp/.env
docker compose up --build

O compose não inclui o frontend nem o backend_mock; para testar com mock externo no Docker, adicione um serviço adicional ou rode o mock localmente e ajuste as URLs conforme a rede do container.

Lista de parâmetros .env

Abaixo estão os parâmetros encontrados em .env.example, explicados por finalidade. Os valores concretos devem ser preenchidos no .env local ou por secrets. Não copie tokens/senhas reais para documentação ou repositório.

Geral

Parâmetro	Para que serve
APP_NAME	Nome lógico da aplicação usado em logs, telemetria e identificação operacional.
APP_ENV	Ambiente de execução, por exemplo local, dev, hml ou prod.
LOG_LEVEL	Nível de log da aplicação Python/FastAPI.
API_HOST	Host/IP usado pelo Uvicorn para publicar o backend.
API_PORT	Porta HTTP do backend do agente.
CORS_ORIGINS	Origens permitidas para chamadas do frontend/browser.

Mapeado a partir das variáveis TIM_LLM_* do legado.

Parâmetro	Para que serve
LLM_PROVIDER	Provider principal de LLM usado pelo Agent Framework OCI.
LLM_TEMPERATURE	Temperatura padrão do modelo para controlar criatividade/variação.
LLM_MAX_TOKENS	Limite máximo padrão de tokens de resposta.
LLM_TIMEOUT_SECONDS	Timeout padrão para chamadas ao LLM; zero normalmente significa sem timeout específico.
OCI_GENAI_BASE_URL	Endpoint/base URL do serviço OCI Generative AI ou endpoint dedicado.
OCI_GENAI_MODEL	Modelo ou endpoint OCID usado pelo OCI Generative AI.
OCI_GENAI_API_KEY	Chave de API quando o provider usa modo compatível com API key.
OCI_CONFIG_FILE	Caminho do arquivo de configuração OCI local.
OCI_PROFILE	Profile OCI dentro do arquivo config.
OCI_COMPARTMENT_ID	OCID do compartment onde ficam os recursos de GenAI/embedding.
OCI_REGION	Região OCI usada pelo SDK/serviços.

Variáveis OCI legadas mantidas para compatibilidade com adapters/scripts.

Parâmetro	Para que serve
TIM_LLM_PROVIDER	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_MODEL	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_API_KEY	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_BASE_URL	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_API_VERSION	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_TEMPERATURE	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_MAX_TOKENS	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_REQUEST_TIMEOUT	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_EXTRA	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_OCI_VARIANT	Configuração legada OCI usada por adapters/scripts do Agent Contas FIRST.
TIM_LLM_OCI_MODEL_ID_20B	OCID/model id legado para variante específica do LLM OCI.
TIM_LLM_OCI_MODEL_ID_120B	OCID/model id legado para variante específica do LLM OCI.
TIM_LLM_OCI_SERVICE_ENDPOINT	Configuração legada OCI usada por adapters/scripts do Agent Contas FIRST.
TIM_LLM_OCI_MODEL_KWARGS	JSON com parâmetros do modelo OCI legado, como temperature, top_p, max_tokens e reasoning_effort.
TIM_LLM_OCI_MODEL_KWARGS_20B	JSON com parâmetros do modelo OCI legado, como temperature, top_p, max_tokens e reasoning_effort.
TIM_LLM_OCI_MODEL_KWARGS_120B	JSON com parâmetros do modelo OCI legado, como temperature, top_p, max_tokens e reasoning_effort.
TIM_LLM_OCI_COMPARTMENT_ID	Configuração legada OCI usada por adapters/scripts do Agent Contas FIRST.
TIM_OCI_USER	Credencial/configuração OCI legada usada pelos adapters do legado.
TIM_OCI_FINGERPRINT	Credencial/configuração OCI legada usada pelos adapters do legado.
TIM_OCI_TENANCY	Credencial/configuração OCI legada usada pelos adapters do legado.
TIM_OCI_REGION	Credencial/configuração OCI legada usada pelos adapters do legado.
TIM_OCI_KEY_FILE	Credencial/configuração OCI legada usada pelos adapters do legado.
TIM_LLM_OCI_AUTH_FILE_LOCATION	Configuração legada OCI usada por adapters/scripts do Agent Contas FIRST.

Repositórios / persistência do framework

Parâmetro	Para que serve
SESSION_REPOSITORY_PROVIDER	Provider do repositório de sessões do framework, como memory ou autonomous.
MEMORY_REPOSITORY_PROVIDER	Provider da memória conversacional/histórico.
CHECKPOINT_REPOSITORY_PROVIDER	Provider de checkpoints LangGraph.
USAGE_REPOSITORY_PROVIDER	Provider para gravação de uso/tokens/custo.
TIM_STATE_BACKEND	Backend legado de estado mantido por compatibilidade.

Autonomous DB / Oracle Store

Parâmetro	Para que serve
ADB_USER	Usuário do Autonomous Database para persistência/RAG.
ADB_PASSWORD	Senha do Autonomous Database. Valor sensível; não commitar.
ADB_DSN	DSN/connect string do Autonomous Database.
ADB_WALLET_LOCATION	Diretório do wallet ADB, quando aplicável.
ADB_WALLET_PASSWORD	Senha do wallet ADB. Valor sensível; não commitar.
ADB_TABLE_PREFIX	Prefixo das tabelas criadas/usadas pelo framework.
TIM_DB_TNS_NAME	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.
TIM_DB_CONNECT_STRING	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.
TIM_DB_USER	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.
TIM_DB_PASSWORD	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.
TIM_DB_WALLET_PASSWORD	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.
TIM_DB_USE_WALLET	Configuração de banco Oracle/ADB legada TIM mantida para compatibilidade.

RAG / Vector Store do framework

Parâmetro	Para que serve
VECTOR_STORE_PROVIDER	Provider do vector store/RAG, como memory ou autonomous.
GRAPH_STORE_PROVIDER	Provider do graph store, quando habilitado.
RAG_TOP_K	Quantidade máxima de documentos/chunks recuperados por consulta RAG.
EMBEDDING_PROVIDER	Provider de embeddings, como mock ou oci.
OCI_EMBEDDING_MODEL	Modelo OCI de embedding usado para indexação/consulta.
RAG_FILE_GLOBS	Extensões/padrões de arquivos aceitos na ingestão RAG.
TIM_RAG_ENABLED	Liga/desliga compatibilidade RAG do legado TIM.
TIM_RAG_OCI_SERVICE_ENDPOINT	Configuração RAG legada TIM mantida para compatibilidade com adapters/scripts.
TIM_RAG_DB_USER	Configuração RAG legada TIM mantida para compatibilidade com adapters/scripts.
TIM_RAG_DB_PASSWORD	Configuração RAG legada TIM mantida para compatibilidade com adapters/scripts.
TIM_RAG_DB_DSN	Configuração RAG legada TIM mantida para compatibilidade com adapters/scripts.

Langfuse / observabilidade

Parâmetro	Para que serve
ENABLE_LANGFUSE	Liga/desliga envio de traces para Langfuse.
LANGFUSE_PUBLIC_KEY	Chave pública Langfuse. Valor sensível operacional.
LANGFUSE_SECRET_KEY	Chave secreta Langfuse. Valor sensível; não commitar.
LANGFUSE_HOST	URL do servidor Langfuse.
ENABLE_OTEL	Liga/desliga exportação OpenTelemetry.
TIM_LLM_GATEWAY_LANGFUSE_PUBLIC_KEY	Configuração legada Langfuse do LLM Gateway (public_key).
TIM_LLM_GATEWAY_LANGFUSE_SECRET_KEY	Configuração legada Langfuse do LLM Gateway (secret_key).
TIM_LLM_GATEWAY_LANGFUSE_HOST	Configuração legada Langfuse do LLM Gateway (host).
TIM_LLM_GATEWAY_LANGFUSE_DEFAULT_LABEL	Configuração legada Langfuse do LLM Gateway (default_label).
TIM_LLM_GATEWAY_LANGFUSE_CACHE_TTL_SECONDS	Configuração legada Langfuse do LLM Gateway (cache_ttl_seconds).
TIM_LLM_GATEWAY_LANGFUSE_MAX_RETRIES	Configuração legada Langfuse do LLM Gateway (max_retries).
TIM_LLM_GATEWAY_LANGFUSE_FETCH_TIMEOUT_SECONDS	Configuração legada Langfuse do LLM Gateway (fetch_timeout_seconds).
TIM_LLM_GATEWAY_LANGFUSE_MASK_SENSITIVE_DATA	Configuração legada Langfuse do LLM Gateway (mask_sensitive_data).
TIM_AGENT_FRAMEWORK_LOG_EXPORT_ENABLED	Parâmetro de compatibilidade do projeto; revisar uso específico no código/configuração antes de remover.
ENABLE_ANALYTICS	Liga/desliga publisher analítico do framework.
ANALYTICS_PROVIDERS	Lista/provider de analytics, por exemplo noop ou oci_streaming.
ENABLE_OCI_STREAMING	Liga/desliga integração com OCI Streaming.

Guardrails / Supervisor / Judges do framework

Parâmetro	Para que serve
ENABLE_INPUT_GUARDRAILS	Ativa guardrails de entrada antes do roteamento/agente.
ENABLE_OUTPUT_GUARDRAILS	Ativa guardrails de saída depois da resposta do agente.
ENABLE_JUDGES	Ativa judges pós-resposta.
ENABLE_SUPERVISOR	Ativa supervisor/validação de fluxo do framework.
ENABLE_OUTPUT_SUPERVISOR	Ativa revisão/retry da resposta antes da entrega.
ENABLE_PARALLEL_GUARDRAILS	Executa guardrails em paralelo quando suportado.
GUARDRAILS_FAIL_FAST	Interrompe no primeiro guardrail bloqueante.
OUTPUT_SUPERVISOR_MAX_RETRIES	Número máximo de tentativas de correção do Output Supervisor.
GUARDRAILS_CONFIG_PATH	Caminho do YAML de guardrails.
JUDGES_CONFIG_PATH	Caminho do YAML de judges.
PROMPT_POLICY_PATH	Caminho da política de prompt.
USE_MOCK_LLM	Força LLM mock para teste local sem provider real.
GUARDRAIL_LLM	Perfil/modelo usado pelos guardrails LLM.

Channel / Routing / MCP framework

Parâmetro	Para que serve
DEFAULT_CHANNEL	Canal padrão quando não informado na request.
FRAMEWORK_CHANNEL_INPUT_MODE	Modo do Channel Gateway: embedded ou external.
ENABLE_VOICE_ADAPTER	Habilita adapter de voz.
ENABLE_WHATSAPP_ADAPTER	Habilita adapter WhatsApp.
ENABLE_TEXT_ADAPTER	Habilita adapter texto/web.
ROUTING_CONFIG_PATH	Caminho do YAML de roteamento/intents.
ENABLE_LLM_ROUTER	Liga router por LLM além das regras/YAML.
ROUTING_MODE	Modo de roteamento do framework.
ENABLE_MCP_TOOLS	Liga/desliga execução de tools MCP.
MCP_SERVERS_CONFIG_PATH	Caminho do YAML com servidores MCP.
TOOLS_CONFIG_PATH	Caminho do catálogo de tools MCP.
MCP_PARAMETER_MAPPING_PATH	Caminho do mapeamento BusinessContext -> argumentos das tools.
MCP_TOOL_TIMEOUT_SECONDS	Timeout padrão das chamadas MCP.
IDENTITY_CONFIG_PATH	Caminho do YAML do IdentityResolver.
ENABLE_REDIS_CACHE	Liga Redis para cache distribuído.
REDIS_URL	URL de conexão Redis.
ENABLE_CONVERSATION_SUMMARY_MEMORY	Liga memória sumarizada de conversa.
MEMORY_CONTEXT_STRATEGY	Estratégia de contexto de memória, por exemplo summary.
MEMORY_HISTORY_LIMIT	Limite de mensagens mantidas no histórico.
MEMORY_RECENT_MESSAGES_LIMIT	Quantidade de mensagens recentes injetadas no prompt.
MEMORY_SUMMARY_TRIGGER_MESSAGES	Número de mensagens que dispara sumarização.
MEMORY_MAX_SUMMARY_CHARS	Tamanho máximo do resumo de memória.
MEMORY_SUMMARY_USE_LLM	Usa LLM para gerar resumo de memória.
MEMORY_INJECT_RECENT_MESSAGES	Injeta mensagens recentes no contexto do agente.
MEMORY_INJECT_SUMMARY	Injeta resumo da conversa no contexto do agente.

MCP legacy TIM/FIRST - integração real por padrão

Parâmetro	Para que serve
TIM_MCP_USE_MOCK	Liga mock interno do MCP. Se false, MCP chama endpoints externos configurados.
TIM_MCP_TIMEOUT_SECONDS	Timeout padrão do MCP legado.
TIM_GATEWAY_RETRY_MAX_RETRIES	Número máximo de retries nas chamadas externas TIM.
TIM_GATEWAY_RETRY_BACKOFF_FACTOR	Fator de backoff entre retries.
TIM_GATEWAY_DEFAULT_TIMEOUT	Timeout padrão do gateway HTTP externo.
TIM_DEFAULT_AUTH	Authorization default para endpoints TIM quando não há auth específico.
TIM_CLIENT_ID	Client ID padrão enviado às APIs TIM/FIRST.
TIM_USER_ID	Usuário técnico/default enviado em payloads/headers.
TIM_DEFAULT_CLIENT_ID	Client ID fallback para chamadas externas.
TIM_DEFAULT_CSP_ID	CSP ID padrão para VAS/serviços.
TIM_DEFAULT_CHANNEL	Canal default moderno para APIs TIM.
TIM_DEFAULT_CHANNEL_LEGACY	Canal default compatível com legado.
TIM_AUTHORIZATION_OAM	Token/header OAM quando a API exigir.
TIM_CN_FIELD	Campo CN legado opcional para headers/payloads.
TIM_TYPE_FIELD	Campo type legado opcional para headers/payloads.

Consulta VAS

Parâmetro	Para que serve
TIM_QUERY_VAS_URL	URL do endpoint externo para query vas.
TIM_QUERY_VAS_AUTH	Header Authorization específico para query vas. Valor sensível.
TIM_QUERY_VAS_TIMEOUT	Timeout em segundos para query vas.
TIM_URL_CONSULTA_VAS	Alias legado de URL para endpoint TIM; mantido para compatibilidade com nomes antigos.
TIM_CONSULTA_AUTH	Header Authorization específico para consulta. Valor sensível.
TIM_CONSULTA_TIMEOUT	Timeout em segundos para consulta.

Bloqueio VAS

Parâmetro	Para que serve
TIM_BLOCK_VAS_URL	URL do endpoint externo para block vas.
TIM_BLOCK_VAS_AUTH	Header Authorization específico para block vas. Valor sensível.
TIM_BLOCK_VAS_TIMEOUT	Timeout em segundos para block vas.
TIM_BLOCK_VAS_CLIENT_ID	Client ID específico usado em block vas.
TIM_BLOCK_VAS_OPERATION_TYPE	Tipo de operação enviado para block vas.
TIM_BLOCK_VAS_PAYLOAD_MODE	Modo de montagem do payload para block vas.
TIM_BLOCK_VAS_ACCEPT_ENCODING	Header Accept-Encoding usado em block vas.
TIM_URL_BLOQUEIO_VAS	Alias legado de URL para endpoint TIM; mantido para compatibilidade com nomes antigos.
TIM_BLOQUEIO_AUTH	Header Authorization específico para bloqueio. Valor sensível.
TIM_BLOQUEIO_TIMEOUT	Timeout em segundos para bloqueio.
TIM_BLOQUEIO_OPERATION_TYPE	Tipo de operação enviado para bloqueio.
TIM_BLOQUEIO_ACCEPT_ENCODING	Header Accept-Encoding usado em bloqueio.

Cancelamento VAS

Parâmetro	Para que serve
TIM_CANCEL_VAS_URL	URL do endpoint externo para cancel vas.
TIM_CANCEL_VAS_AUTH	Header Authorization específico para cancel vas. Valor sensível.
TIM_CANCEL_VAS_TIMEOUT	Timeout em segundos para cancel vas.
TIM_CANCEL_VAS_CLIENT_ID	Client ID específico usado em cancel vas.
TIM_CANCELAMENTO_URL	URL do endpoint externo para cancelamento.
TIM_CANCELAMENTO_AUTH	Header Authorization específico para cancelamento. Valor sensível.
TIM_CANCELAMENTO_TIMEOUT	Timeout em segundos para cancelamento.

Contrato

Parâmetro	Para que serve
TIM_CONTRATO_URL	URL do endpoint externo para contrato.
TIM_CONTRATO_AUTH	Header Authorization específico para contrato. Valor sensível.
TIM_CONTRATO_TIMEOUT	Timeout em segundos para contrato.

Complete invoices / fatura completa

Parâmetro	Para que serve
TIM_COMPLETE_INVOICES_URL	URL do endpoint externo para complete invoices.
TIM_COMPLETE_INVOICES_AUTH	Header Authorization específico para complete invoices. Valor sensível.
TIM_COMPLETE_INVOICES_TIMEOUT	Timeout em segundos para complete invoices.
TIM_COMPLETE_INVOICES_CLIENT_ID	Client ID específico usado em complete invoices.

Perfil de fatura

Parâmetro	Para que serve
TIM_PROFILE_BILL_URL	URL do endpoint externo para profile bill.
TIM_PROFILE_BILL_AUTH	Header Authorization específico para profile bill. Valor sensível.
TIM_PROFILE_BILL_TIMEOUT	Timeout em segundos para profile bill.
TIM_URL_PERFIL_FATURA	Alias legado de URL para endpoint TIM; mantido para compatibilidade com nomes antigos.
TIM_PROFILE_FULL_URL	URL do endpoint externo para profile full.

Divergência / billing analysis

Parâmetro	Para que serve
TIM_DIVERGENCIA_URL	URL do endpoint externo para divergencia.
TIM_DIVERGENCIA_AUTH	Header Authorization específico para divergencia. Valor sensível.
TIM_INVOICE_EXPLANATION_URL	URL do endpoint externo para invoice explanation.
TIM_INVOICE_EXPLANATION_AUTH	Header Authorization específico para invoice explanation. Valor sensível.

Bill/PDF / invoice recover

Parâmetro	Para que serve
TIM_BILL_PDF_URL	URL do endpoint externo para bill pdf.
TIM_BILL_PDF_AUTH	Header Authorization específico para bill pdf. Valor sensível.
TIM_BILL_PDF_TIMEOUT	Timeout em segundos para bill pdf.
TIM_BILL_PDF_CLIENT_ID	Client ID específico usado em bill pdf.
TIM_URL_INVOICE_RECOVER	Alias legado de URL para endpoint TIM; mantido para compatibilidade com nomes antigos.
TIM_INVOICE_RECOVER_AUTH	Header Authorization específico para invoice recover. Valor sensível.
TIM_INVOICE_RECOVER_TIMEOUT	Timeout em segundos para invoice recover.
TIM_INVOICE_RECOVER_CLIENT_ID	Client ID específico usado em invoice recover.

Protocolo / backOfficeSRopening

Parâmetro	Para que serve
TIM_PROTOCOL_URL	URL do endpoint externo para protocol.
TIM_PROTOCOL_AUTH	Header Authorization específico para protocol. Valor sensível.
TIM_PROTOCOL_TIMEOUT	Timeout em segundos para protocol.

Contestação/SR

Parâmetro	Para que serve
TIM_CUSTOMER_CONTESTATION_URL	URL do endpoint externo para customer contestation.
TIM_CUSTOMER_CONTESTATION_AUTH	Header Authorization específico para customer contestation. Valor sensível.
TIM_CUSTOMER_CONTESTATION_TIMEOUT	Timeout em segundos para customer contestation.
TIM_CUSTOMER_CONTESTATION_CLIENT_ID	Client ID específico usado em customer contestation.
TIM_CUSTOMER_CONTESTATION_USER_ID	Usuário técnico específico usado em customer contestation.

Status SR

Parâmetro	Para que serve
TIM_SERVICE_REQUEST_STATUS_URL	URL do endpoint externo para service request status.
TIM_SERVICE_REQUEST_STATUS_AUTH	Header Authorization específico para service request status. Valor sensível.
TIM_SERVICE_REQUEST_STATUS_TIMEOUT	Timeout em segundos para service request status.

SMS

Parâmetro	Para que serve
TIM_SMS_URL	URL do endpoint externo para sms.
TIM_SMS_AUTH	Header Authorization específico para sms. Valor sensível.
TIM_SMS_TIMEOUT	Timeout em segundos para sms.
TIM_SMS_CLIENT_ID	Client ID específico usado em sms.
TIM_SMS_SENDER_ADDRESS	Endereço/remetente usado no envio de SMS.
TIM_SMS_SENDER_NAME	Nome do remetente usado no envio de SMS.
TIM_SMS_TOKEN_URL	Configuração para obtenção de token OAuth/serviço do envio de SMS.
TIM_SMS_TOKEN_CLIENT_ID	Configuração para obtenção de token OAuth/serviço do envio de SMS.
TIM_SMS_TOKEN_CLIENT_SECRET	Configuração para obtenção de token OAuth/serviço do envio de SMS.
TIM_SMS_TOKEN_SCOPE	Configuração para obtenção de token OAuth/serviço do envio de SMS.
TIM_SMS_TOKEN_AUDIENCE	Configuração para obtenção de token OAuth/serviço do envio de SMS.
TIM_SMS_TOKEN_TIMEOUT	Configuração para obtenção de token OAuth/serviço do envio de SMS.
SMS_BARCODE_AUTH	Authorization alternativo para envio de SMS com código de barras.

Tracking activities

Parâmetro	Para que serve
TIM_TRACKING_ACTIVITIES_URL	URL do endpoint externo para tracking activities.
TIM_TRACKING_ACTIVITIES_AUTH	Header Authorization específico para tracking activities. Valor sensível.
TIM_TRACKING_ACTIVITIES_TIMEOUT	Timeout em segundos para tracking activities.
TIM_TRACKING_ACTIVITIES_USER_LOGIN	Login técnico usado em tracking activities.
TIM_TRACKING_ACTIVITIES_CHANNEL	Canal enviado nas chamadas de tracking activities.
TIM_TRACKING_ACTIVITIES_CLIENT_ID	Client ID específico usado em tracking activities.

Legacy app / workflows

Parâmetro	Para que serve
TIM_WORKFLOWS_DIR	Diretório de workflows legados mantido como referência.
TIM_WORKFLOW_POSTGRES_DSN	DSN Postgres legado, se algum workflow antigo exigir.
TIM_APP_HOST	Host legado da aplicação TIM.
TIM_APP_PORT	Porta legada da aplicação TIM.
TIM_APP_RELOAD	Reload legado do app TIM.
TIM_APP_LOG_LEVEL	Log level legado do app TIM.

LLM Gateway legado

Parâmetro	Para que serve
TIM_LLM_GATEWAY_SOURCES	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_LOCAL_DIR	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_CAPABILITIES_DIR	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_LANGGRAPH_URL	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_LANGGRAPH_TIMEOUT	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_FALLBACK_PROMPT_ID	Configuração legada do LLM Gateway TIM mantida para compatibilidade.
TIM_LLM_GATEWAY_FALLBACK_PROMPT_CONTENT	Configuração legada do LLM Gateway TIM mantida para compatibilidade.

Pub/Sub / export legado

Parâmetro	Para que serve
GCP_PROJECT_ID	Projeto GCP legado usado em Pub/Sub/exportações.
AGENT_PUBSUB_TOPIC	Tópico Pub/Sub legado para curadoria/ingestão.
TIM_PUBSUB_DIRECT_ENABLED	Liga publicação direta no Pub/Sub legado.
GOOGLE_APPLICATION_CREDENTIALS	Caminho do arquivo de credenciais GCP.

Mock legado explicitamente desligado

Parâmetro	Para que serve
TIM_MOCK_LATENCY_MS	Latência artificial do mock legado.
TIM_MOCK_FAILURES	Lista/configuração de falhas simuladas no mock legado.
TIM_MOCK_FIXTURES_DIR	Diretório de fixtures do mock legado.

Recomendações de operação

1. Para teste local completo, prefira TIM_MCP_USE_MOCK=false com URLs apontando para http://localhost:8001, pois assim você valida backend, MCP e mock externo no mesmo fluxo.
2. Para smoke test rápido apenas do MCP, use TIM_MCP_USE_MOCK=true no MCP e dispense o mock server.
3. Para produção/homologação, substitua URLs do mock pelas APIs reais TIM/FIRST e revise todos os parâmetros *_AUTH, *_CLIENT_ID, timeouts e retry.
4. Não deixe USE_MOCK_LLM=true em ambiente que precise validar chamada real ao LLM.
5. Se VECTOR_STORE_PROVIDER=autonomous, valide ADB_*, EMBEDDING_PROVIDER=oci e OCI_EMBEDDING_MODEL antes de testar RAG.
6. Se ENABLE_LANGFUSE=true, confirme LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY antes de esperar traces.
7. Reinicie MCP e backend sempre que alterar .env, config/tools.yaml, config/mcp_servers.yaml ou config/mcp_parameter_mapping.yaml.

Troubleshooting rápido

Sintoma	Causa provável	Ação
Endpoint externo não configurado para TIM_COMPLETE_INVOICES	URL da API externa não preenchida no .env do MCP.	Configure TIM_COMPLETE_INVOICES_URL ou use TIM_MCP_USE_MOCK=true.
Backend não chama MCP	ENABLE_MCP_TOOLS=false, MCP_SERVERS_CONFIG_PATH errado ou MCP fora do ar.	Verifique /debug/mcp/call/consultar_fatura e http://localhost:8100/health.
Frontend recebe erro CORS	Origem não está em CORS_ORIGINS.	Inclua http://localhost:5173 no .env.
Não aparecem traces no Langfuse	Langfuse desabilitado ou chaves/host incorretos.	Verifique ENABLE_LANGFUSE, LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY.
RAG não retorna documentos	Vector store/embedding não configurados ou base não ingerida.	Teste VECTOR_STORE_PROVIDER=memory/EMBEDDING_PROVIDER=mock ou configure ADB/OCI.
Tool retorna ok=false sem erro	MCP antigo/rota errada ou backend não reiniciado.	Reinicie MCP e backend; confira config/mcp_servers.yaml.

Resumo executivo

Este projeto coloca o Agent Contas FIRST sobre o Agent Framework OCI com uma arquitetura mais limpa: o framework cuida das capacidades transversais corporativas e o código do Contas fica restrito ao domínio de negócio. A integração operacional passa por MCP, com mapeamento canônico de identidade, cache declarativo, RAG nativo, guardrails, judges e observabilidade. Para subir localmente o fluxo completo, use quatro terminais: MCP na porta 8100, mock externo na porta 8001, backend na porta 8000 e frontend na porta 5173.