first commit

config/agents.yaml

@@ -0,0 +1,18 @@
+default_agent_id: contas_first
+agents:
+  - agent_id: contas_first
+    name: Agent Contas FIRST Migrado
+    description: Agente de contas/faturas FIRST reimplementado para usar ao máximo o agent_framework_oci.
+    prompt_policy_path: ./config/agents/contas_first/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/contas_first/guardrails.yaml
+    judges_config_path: ./config/agents/contas_first/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: telecom_contas
+      rag_namespace: contas_first
+      system_prefix: |
+        Você está executando o Agent Contas FIRST migrado para o agent_framework_oci.
+        Use isolamento por tenant/agent/session, BusinessContext canônico,
+        guardrails, judges, memória, RAG, MCP Router e observabilidade do framework.

config/agents/contas_first/guardrails.yaml

@@ -0,0 +1,20 @@
+# Guardrails do contas usando o pipeline calibrado nativo do framework.
+# Não importar pipeline legado do agent_contas_first.
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+  - code: PINJ
+    enabled: true
+  - code: DLEX_IN
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
+  - code: PINJ
+    enabled: true
+  - code: DLEX_OUT
+    enabled: true
+  - code: RAGSEC
+    enabled: true

config/agents/contas_first/judges.yaml

@@ -0,0 +1,16 @@
+enabled: true
+fail_closed: true
+profile: judge
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
+  - name: sentiment
+    enabled: true
+    fail_on_negative: false
+  - name: tone
+    enabled: true
+    fail_closed: true

config/agents/contas_first/prompt_policy.yaml

@@ -0,0 +1,7 @@
+id: contas_first_prompt_policy
+version: 1
+description: Prompt base isolado do agent_contas_first migrado.
+system_prefix: |
+  Você é um agente corporativo de telecom especializado em contas, faturas,
+  pagamentos, segunda via, contestação, planos e serviços VAS.
+  Use dados MCP e RAG como evidência. Não invente informação operacional.

config/guardrails.yaml

@@ -0,0 +1,12 @@
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
+  - code: PINJ
+    enabled: true
+  - code: DLEX_OUT
+    enabled: true

config/identity.yaml

@@ -0,0 +1,52 @@
+identity:
+  version: "2"
+  required:
+    - session_key
+  keys:
+    customer_key:
+      description: Cliente/assinante canônico. Para telecom, normalmente msisdn.
+      sources:
+        - business_context.customer_key
+        - customer_key
+        - msisdn
+        - ani
+        - from
+        - user_id
+    contract_key:
+      description: Fatura, contrato ou asset principal.
+      sources:
+        - business_context.contract_key
+        - contract_key
+        - invoice_id
+        - current_invoice_number
+        - past_invoice_number
+        - asset_id
+    interaction_key:
+      description: Chave externa da interação/call/chat.
+      sources:
+        - business_context.interaction_key
+        - interaction_key
+        - ura_call_id
+        - call_id
+        - message_id
+    account_key:
+      description: Conta de cobrança/conta comercial.
+      sources:
+        - business_context.account_key
+        - account_key
+        - account_id
+        - billing_account_id
+    resource_key:
+      description: Linha/produto/asset específico.
+      sources:
+        - business_context.resource_key
+        - resource_key
+        - asset_id
+        - product_id
+    session_key:
+      description: Sessão técnica estável escopada por tenant e agente.
+      sources:
+        - business_context.session_key
+        - session_key
+        - conversation_key
+        - session_id

config/judges.yaml

@@ -0,0 +1,20 @@
+enabled: true
+fail_closed: true
+profile: judge
+
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
+
+  - name: sentiment
+    enabled: true
+    fail_on_negative: false
+
+  - name: tone
+    enabled: true
+    fail_closed: true

config/mcp_parameter_mapping.yaml

@@ -0,0 +1,76 @@
+mcp_parameter_mapping:
+  defaults:
+    use_mock: false
+  tools:
+    consultar_fatura:
+      map:
+        customer_key: msisdn
+        contract_key: invoice_id
+        account_key: customer_id
+        interaction_key: ura_call_id
+        session_key: session_id
+    consultar_pagamentos:
+      map:
+        customer_key: msisdn
+        account_key: customer_id
+        interaction_key: ura_call_id
+        session_key: session_id
+    consultar_plano:
+      map:
+        customer_key: msisdn
+        resource_key: asset_id
+        account_key: customer_id
+        session_key: session_id
+    listar_servicos:
+      map:
+        customer_key: msisdn
+        resource_key: asset_id
+        session_key: session_id
+    recuperar_pdf_fatura:
+      map:
+        customer_key: msisdn
+        contract_key: invoice_id
+        account_key: customer_id
+        session_key: session_id
+    registrar_protocolo:
+      map:
+        customer_key: msisdn
+        interaction_key: interaction_call_id
+        session_key: session_id
+    abrir_contestacao:
+      map:
+        customer_key: msisdn
+        contract_key: invoice_id
+        account_key: customer_id
+        interaction_key: ura_call_id
+        session_key: session_id
+    consultar_status_sr:
+      map:
+        customer_key: msisdn
+        interaction_key: protocol_number
+        session_key: session_id
+    atualizar_status_sr:
+      map:
+        customer_key: msisdn
+        interaction_key: protocol_number
+        session_key: session_id
+    cancelar_vas:
+      map:
+        customer_key: msisdn
+        resource_key: app_id
+        session_key: session_id
+    bloquear_vas:
+      map:
+        customer_key: msisdn
+        resource_key: app_id
+        session_key: session_id
+    enviar_sms:
+      map:
+        customer_key: msisdn
+        session_key: session_id
+    registrar_tracking:
+      map:
+        customer_key: msisdn
+        contract_key: invoice_id
+        interaction_key: protocol_number
+        session_key: session_id

config/mcp_servers.docker.yaml

@@ -0,0 +1,6 @@
+servers:
+  legacy_tim:
+    transport: http
+    endpoint: http://legacy-tim-mcp:8100/mcp
+    enabled: true
+    description: MCP Server adaptador dos serviços externos legados do Agent Contas FIRST/TIM.

config/mcp_servers.yaml

@@ -0,0 +1,6 @@
+servers:
+  legacy_tim:
+    transport: http
+    endpoint: http://localhost:8100/mcp
+    enabled: true
+    description: MCP Server adaptador dos serviços externos legados do Agent Contas FIRST/TIM.

config/prompt_policy.yaml

@@ -0,0 +1,8 @@
+prompt_policy:
+  default_profile: contas_agent
+  profiles:
+    contas_agent:
+      system_prefix: |
+        Agent Contas FIRST migrado. Use BusinessContext, MCP, RAG, memória,
+        guardrails e judges do framework. Não duplique regras legadas.
+      tone: objetivo, claro, seguro e auditável

config/routing.yaml

@@ -0,0 +1,143 @@
+router:
+  mode: router
+  fallback_agent: contas_agent
+  confidence_threshold: 0.55
+  allow_handoff: false
+
+state_policies:
+  - state: WAITING_BILLING_CONFIRMATION
+    agent: contas_agent
+    description: Mantém respostas curtas de confirmação dentro do fluxo de contas.
+  - state: WAITING_SERVICE_CONFIRMATION
+    agent: contas_agent
+    description: Mantém confirmações de plano/serviço/VAS dentro do Agent Contas.
+
+intents:
+  - name: billing_invoice_explanation
+    domain: telecom_contas
+    agent: contas_agent
+    description: Explicação de fatura, divergência de valor, cobrança proporcional, itens da conta e dúvidas de vencimento.
+    priority: 10
+    mcp_tools: [consultar_fatura, consultar_pagamentos]
+    keywords: [fatura, conta, cobrança, valor, alto, divergente, proporcional, pro rata, vencimento, boleto, explicação]
+    examples:
+      - Minha fatura veio alta.
+      - Quero entender uma cobrança proporcional.
+      - Por que minha conta mudou de valor?
+
+  - name: billing_payment_status
+    domain: telecom_contas
+    agent: contas_agent
+    description: Consulta pagamentos, baixa, status de pagamento e histórico.
+    priority: 20
+    mcp_tools: [consultar_pagamentos, consultar_fatura]
+    keywords: [pagamento, paguei, baixa, comprovante, histórico, aberto, quitado]
+    examples:
+      - Meu pagamento já caiu?
+      - Quero consultar meus pagamentos.
+
+  - name: billing_second_copy
+    domain: telecom_contas
+    agent: contas_agent
+    description: Segunda via, código de barras e dados da fatura atual.
+    priority: 30
+    mcp_tools: [consultar_fatura]
+    keywords: [segunda via, boleto, código de barras, barcode, copiar linha digitável]
+    examples:
+      - Preciso da segunda via da conta.
+      - Me envie o boleto da fatura.
+
+  - name: billing_contestation
+    domain: telecom_contas
+    agent: contas_agent
+    description: Contestação de cobrança, análise de item de fatura e abertura de fluxo com confirmação.
+    priority: 40
+    mcp_tools: [consultar_fatura, consultar_pagamentos]
+    keywords: [contestar, contestação, cobrança indevida, não reconheço, reclamar, ajustar, crédito]
+    examples:
+      - Quero contestar essa cobrança.
+      - Não reconheço um item da fatura.
+
+  - name: service_plan_information
+    domain: telecom_contas
+    agent: contas_agent
+    description: Consulta plano, pacote, asset, internet, roaming e benefícios.
+    priority: 50
+    mcp_tools: [consultar_plano, listar_servicos]
+    keywords: [plano, pacote, internet, roaming, benefício, asset, produto]
+    examples:
+      - Qual é meu plano?
+      - Tenho roaming incluso?
+
+  - name: vas_services_information
+    domain: telecom_contas
+    agent: contas_agent
+    description: Serviços adicionais, VAS, assinaturas, bloqueio/cancelamento informativo.
+    priority: 60
+    mcp_tools: [listar_servicos, consultar_plano]
+    keywords: [vas, serviço adicional, assinatura, serviços digitais, cancelar serviço, bloquear serviço]
+    examples:
+      - Quais serviços VAS estão ativos?
+      - Quero entender serviços digitais na minha conta.
+
+  - name: generic_billing_rag
+    domain: telecom_contas
+    agent: contas_agent
+    description: Perguntas de política, regras de atendimento e conhecimento sem necessidade inicial de tool operacional.
+    priority: 90
+    mcp_tools: []
+    keywords: [política, regra, procedimento, anatel, prazo, atendimento]
+    examples:
+      - Qual é a regra para cobrança proporcional?
+
+  - name: billing_protocol_status
+    domain: telecom_contas
+    agent: contas_agent
+    description: Consulta status de protocolo/SR/contestação.
+    priority: 35
+    mcp_tools: [consultar_status_sr]
+    keywords: [protocolo, sr, status da contestação, acompanhamento, andamento]
+    examples:
+      - Quero saber o status do meu protocolo.
+      - Como está minha contestação?
+
+  - name: billing_protocol_register
+    domain: telecom_contas
+    agent: contas_agent
+    description: Registro de protocolo de atendimento quando o fluxo exigir e houver confirmação.
+    priority: 75
+    mcp_tools: [registrar_protocolo]
+    keywords: [gerar protocolo, registrar protocolo, abrir protocolo]
+    examples:
+      - Gere um protocolo para este atendimento.
+
+  - name: vas_cancel_or_block
+    domain: telecom_contas
+    agent: contas_agent
+    description: Cancelamento/bloqueio de VAS/SVA/serviço adicional após confirmação explícita.
+    priority: 45
+    mcp_tools: [listar_servicos, cancelar_vas, bloquear_vas, registrar_protocolo]
+    keywords: [cancelar vas, cancelar serviço, bloquear vas, bloquear serviço, remover assinatura]
+    examples:
+      - Quero cancelar esse serviço adicional.
+      - Bloqueie esse VAS.
+
+  - name: send_billing_sms
+    domain: telecom_contas
+    agent: contas_agent
+    description: Envio de SMS com link ou informação de atendimento quando autorizado.
+    priority: 80
+    mcp_tools: [enviar_sms]
+    keywords: [enviar sms, mandar sms, envia por mensagem, link por sms]
+    examples:
+      - Envie o boleto por SMS.
+
+  - name: tracking_activity
+    domain: telecom_contas
+    agent: contas_agent
+    description: Registro de tracking/activity operacional.
+    priority: 85
+    mcp_tools: [registrar_tracking]
+    keywords: [registrar atividade, tracking, registrar acompanhamento]
+    examples:
+      - Registre a atividade do atendimento.

config/tools.yaml

@@ -0,0 +1,167 @@
+tools:
+  consultar_fatura:
+    description: Consulta dados de fatura, valores, vencimento, itens, status e linha digitável.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 300 }
+    args_schema:
+      msisdn: string
+      invoice_id: string
+      customer_id: string
+
+  consultar_pagamentos:
+    description: Consulta histórico/status de pagamentos do cliente.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 300 }
+    args_schema:
+      msisdn: string
+      customer_id: string
+
+  consultar_plano:
+    description: Consulta contrato/plano ativo e atributos comerciais.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 600 }
+    args_schema:
+      msisdn: string
+      asset_id: string
+      customer_id: string
+
+  listar_servicos:
+    description: Lista serviços ativos, VAS, SVA, bundles e benefícios da linha.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 600 }
+    args_schema:
+      msisdn: string
+      asset_id: string
+
+  recuperar_pdf_fatura:
+    description: Recupera PDF/segunda via da fatura quando disponível.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 300 }
+    args_schema:
+      msisdn: string
+      invoice_id: string
+      customer_id: string
+      output: string
+
+  registrar_protocolo:
+    description: Registra protocolo de atendimento nos serviços legados/Siebel quando aplicável.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      protocol_number: string
+      interaction_call_id: string
+      reason: string
+      channel: string
+
+  abrir_contestacao:
+    description: Abre contestação de cobrança/SR para itens de fatura após confirmação.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn, invoice_id]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      invoice_id: string
+      customer_id: string
+      sr: string
+      items: list
+      reason: string
+      amount: number
+
+  consultar_status_sr:
+    description: Consulta status de SR/protocolo de contestação ou atendimento.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: query
+    cache: { enabled: true, ttl_seconds: 180 }
+    args_schema:
+      msisdn: string
+      sr: string
+      protocol_number: string
+
+  atualizar_status_sr:
+    description: Atualiza status de SR/protocolo nos serviços externos.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn, protocol_number]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      protocol_number: string
+      status: string
+      notes: string
+
+  cancelar_vas:
+    description: Solicita cancelamento de VAS/SVA/serviço adicional após confirmação explícita.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      app_id: string
+      service_id: string
+      csp_id: string
+
+  bloquear_vas:
+    description: Solicita bloqueio de VAS/SVA/serviço adicional após confirmação explícita.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      app_id: string
+      service_id: string
+      csp_id: string
+
+  enviar_sms:
+    description: Envia SMS ao cliente com link/informação quando o fluxo exigir.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [msisdn]
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      message: string
+      long_url: string
+      notify_url: string
+
+  registrar_tracking:
+    description: Registra tracking/activity de atendimento ou fatura nos serviços externos.
+    mcp_server: legacy_tim
+    enabled: true
+    tool_type: action
+    confirmation_required: false
+    cache: { enabled: false }
+    args_schema:
+      msisdn: string
+      protocol_number: string
+      invoice_id: string
+      activity_type: string
+      activity_status: string