# 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 é:

```text
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:

```http
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:

```bash
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:

```bash
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`:

```env
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

```bash
cd first_contas
./scripts/start_legacy_tim_mcp.sh
```

Alternativa manual:

```bash
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:

```bash
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

```bash
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:

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

### Terminal 3 — Backend do agente

```bash
cd first_contas
./scripts/start_backend.sh
```

Alternativa manual:

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

Teste:

```bash
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:

```bash
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:

```text
http://localhost:8000
```

E use `agent_id`:

```text
contas_first
```

Payload mínimo esperado pelo backend:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```bash
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`.