agent_contas/MANUAL_REGRAS_AGENTE_CONTAS.md

Manual Detalhado de Regras do Agente de Contas

Versão aprofundada gerada a partir do pacote agent_contas_oci_template (9)(1).zip. O objetivo é permitir entender por que o agente escolheu uma regra, como os componentes estão amarrados e onde diagnosticar decisões inesperadas.

1. Como ler este manual

Cada regra é documentada em seis níveis:

1. Intenção de negócio — o que a regra significa e o que ela não significa.
2. Roteamento — explicação atributo por atributo do bloco correspondente em config/routing.yaml.
3. Descoberta da intent — como o framework chega à intent: estado, keywords, LLM e fallback.
4. Tools e parâmetros — o que cada tool consulta/processa/executa, dados necessários, pre-validation, confirmação e retorno.
5. Workflow — nós, actions Python, condições, pause/resume e término.
6. Diagnóstico — exemplos que mostram por que duas frases parecidas podem produzir tratamentos diferentes.

A distinção mais importante é:

intent != tool != workflow

A intent descreve o objetivo conversacional. A tool representa uma capability. O workflow orquestra uma execução. E, em regras como VAS, o domínio ainda pode reclassificar a entidade e trocar a tool efetiva com base em evidência autoritativa.

2. Como o framework encontra uma intent

A ordem implementada no EnterpriseRouter é:

1. state_policies
   ↓
2. keywords determinísticas
   ↓
3. LLM router, quando ENABLE_LLM_ROUTER=true
   ↓
4. fallback_agent

Antes de tratar uma fala isoladamente, o router verifica estados como WAITING_*_CONFIRMATION e COLLECTING_*_PARAMETERS. Isso impede que uma resposta curta como “sim” seja interpretada como uma nova solicitação.

No matching por keywords existem três estratégias:

• exact: termo único em token ou frase multi-token contida no texto;
• ordered_tokens: permite pequenos tokens entre as palavras da keyword, preservando ordem;
• ordered_content_tokens: tolera conectores curtos omitidos, como variações de “qual é o meu plano” / “qual o meu plano”.

Se mais de uma intent casar, a ordenação é:

menor priority
→ estratégia mais estrita
→ keyword mais longa

Isto é importante: em routing.yaml, priority 110 ganha de priority 145, e não o contrário.

Se não houver keyword suficiente e o LLM router estiver habilitado, o classificador recebe name, description e alguns examples das intents permitidas. A resposta do LLM não inventa agente/tool: esses dados são recuperados do catálogo YAML.

Pedidos compostos podem ainda passar pelo MultiIntentPlanner, que separa objetivos independentes sem transformar parâmetros de uma única ação em intents artificiais.

3. Amarração entre os componentes

flowchart LR
    U["Mensagem do cliente"] --> R["routing.yaml"]
    R --> ST["state_policies / intent"]
    ST --> AG["Agente proprietário"]
    AG --> TL["tools.yaml"]
    TL --> TP["tool_policies.yaml"]
    TL --> PM["mcp_parameter_mapping.yaml"]
    TP --> PV["pre-validation"]
    PM --> MCP["contas_mcp_server"]
    PV --> MCP
    MCP --> IR["classificação de domínio / invoice_resolver"]
    IR --> WF["workflow YAML ou execução direta"]
    WF --> WA["workflow_actions.py"]
    WA --> DS["service.py"]
    DS --> CL["client.py"]
    CL --> ENV[".env + tim_integration_defaults.yaml"]

A seta pre-validation → classificação de domínio é especialmente importante. É nela que um pedido como “cancelar Paramount+” pode deixar de usar a operação de VAS avulso mesmo que a intent inicial tenha sido de cancelamento.

4. Inventário das regras

Intent	Regra	Agente	Prioridade	Tools
contas_no_match	No Match / Clarificação	suporte_contas_agent	200	—
contas_plan_information	Consulta de Plano	faturas_agent	142	consultar_plano
contas_invoice_query	Consulta / Segunda Via de Fatura	faturas_agent	140	consultar_faturas
contas_invoice_explanation	Explicação de Fatura	faturas_agent	150	invoice_explanation
contas_contestation	Contestação de Cobrança	contestacao_agent	120	consultar_faturas, invoice_explanation, contestar_cobranca
contas_vas_cancel	Cancelamento de VAS	contestacao_agent	145	consultar_vas, cancelar_vas_avulso
contas_vas_strategic	VAS Estratégico / Bundle	contestacao_agent	125	consultar_vas, tratar_vas_estrategico
contas_vas_information	Consulta de VAS	vas_agent	110	consultar_vas
contas_vas_history	Histórico de VAS	vas_agent	105	consultar_historico_vas
contas_knowledge	Conhecimento Geral de Contas	suporte_contas_agent	120	—
contas_service_status	Status de Solicitação	suporte_contas_agent	90	consultar_status_solicitacao
contas_pro_rata	Pró-rata	faturas_agent	128	pro_rata
contas_termino_desconto	Término de Desconto	faturas_agent	127	termino_desconto
contas_valor_divergente	Valor Divergente	faturas_agent	126	valor_divergente

5. Regra — No Match / Clarificação

Intent: contas_no_match
Agente: suporte_contas_agent
Domínio: telecom_contas
Prioridade: 200

O que esta regra significa

Fala incompreensível, transcrição corrompida ou fragmento sem informação suficiente para determinar uma solicitação/objeto com segurança. Inclui enunciados que contêm uma palavra de domínio, mas deixam o objeto sem referente recuperável (por exemplo, verbo de cobrança seguido apenas de pronome/indefinido). Não use para assunto fora de escopo, reclamação, pedido de humano, jurídico/Anatel/Procon ou frase compreensível que apenas não corresponda a outra intent.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_no_match	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	suporte_contas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	200	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Fala incompreensível, transcrição corrompida ou fragmento sem informação suficiente para determinar uma solicitação/objeto com segurança. Inclui enunciados que contêm uma palavra de domínio, mas deixam o objeto sem referente recuperável (por exemplo, verbo de cobrança seguido apenas de pronome/indefinido). Não use para assunto fora de escopo, reclamação, pedido de humano, jurídico/Anatel/Procon ou frase compreensível que apenas não corresponda a outra intent.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	—	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	—	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	asdkj qweoi zxcm hã trrr blá qx [fala sem conteúdo inteligível] está cobrando um veio uma aqui	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. Esta regra não possui keywords determinísticas; portanto depende de estado, classificador LLM/fallback ou lógica conversacional específica.
2. Se o caminho LLM for usado, a descrição acima e exemplos como asdkj qweoi zxcm, hã trrr blá qx, [fala sem conteúdo inteligível] entram no catálogo de classificação.
3. Ao escolher a intent, o router entrega agent=suporte_contas_agent e mcp_tools=[]. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Esta intent não declara MCP tools. O tratamento é conversacional, de clarificação ou de conhecimento por mecanismos do agente/framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_no_match e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

6. Regra — Consulta de Plano

Intent: contas_plan_information
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 142

O que esta regra significa

Consulta do plano principal ou dos planos efetivamente contratados na linha, incluindo nome, identificação, valor e dados contratuais do plano atual. Use somente quando a pergunta exigir dados do cliente. Não use para perguntas gerais sobre funcionamento, tarifação, regras, condições ou características de um plano/produto, ainda que o usuário cite o nome de um plano específico.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_plan_information	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	142	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Consulta do plano principal ou dos planos efetivamente contratados na linha, incluindo nome, identificação, valor e dados contratuais do plano atual. Use somente quando a pergunta exigir dados do cliente. Não use para perguntas gerais sobre funcionamento, tarifação, regras, condições ou características de um plano/produto, ainda que o usuário cite o nome de um plano específico.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_plano	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	qual é meu plano qual e meu plano qual é o meu plano qual e o meu plano meu plano contratado plano contratado nome do meu plano que plano eu tenho quais são meus planos quais sao meus planos	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Qual é meu plano? Qual é o meu plano contratado? Que plano eu tenho? Qual o nome do meu plano? Quais são os planos da minha linha? Quanto custa o meu plano atual?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: qual é meu plano, qual e meu plano, qual é o meu plano, qual e o meu plano, meu plano contratado, plano contratado, nome do meu plano, que plano eu tenho.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 142 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Qual é meu plano?, Qual é o meu plano contratado?, Que plano eu tenho? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['consultar_plano']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_plano

O que faz: Consulta exclusivamente o nome e valor do plano ou planos contratados a partir da evidência de billing analysis; não retorna VAS como plano.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna {plans, count, source}. Cada plano contém pelo menos name, value, type e contestable, extraído exclusivamente de billing_analysis.currentInvoice.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_plan_information e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

7. Regra — Consulta / Segunda Via de Fatura

Intent: contas_invoice_query
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 140

O que esta regra significa

Consulta, visualização, obtenção ou segunda via de fatura/conta sem pedido de explicação de cobrança.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_invoice_query	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	140	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Consulta, visualização, obtenção ou segunda via de fatura/conta sem pedido de explicação de cobrança.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_faturas	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	quero minha fatura ver minha fatura consultar fatura consultar minha fatura mostrar minha fatura me mostra minha fatura segunda via segunda via da fatura obter fatura baixar fatura minhas faturas fatura atual última fatura ultima fatura fatura em aberto conta em aberto	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Quero minha fatura Quero ver a minha conta Pode consultar minha fatura atual? Preciso da segunda via da fatura Tenho alguma fatura em aberto?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: quero minha fatura, ver minha fatura, consultar fatura, consultar minha fatura, mostrar minha fatura, me mostra minha fatura, segunda via, segunda via da fatura.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 140 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Quero minha fatura, Quero ver a minha conta, Pode consultar minha fatura atual? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['consultar_faturas']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_faturas

O que faz: Consulta faturas atuais/anteriores, status, vencimento, valor e existência de fatura aberta sem iniciar o workflow de explicação.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o payload de faturas e, quando disponível no contexto enriquecido, invoice_amount, invoice_amount_open, invoice_period, invoice_emissao, invoice_id e customer_id.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_invoice_query e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

8. Regra — Explicação de Fatura

Intent: contas_invoice_explanation
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 150

O que esta regra significa

Explicação, composição, diferença, aumento, variação, dúvida ou não reconhecimento informativo de valores/itens de uma fatura já conhecida. Use esta intent quando o cliente estiver tentando entender uma cobrança ou disser que não reconhece itens/valores, mas ainda não pedir explicitamente contestação, cancelamento, estorno, ajuste ou retirada. Não use para fragmentos que apenas mencionem cobrança sem um objeto/referente recuperável; nesses casos solicite clarificação via contas_no_match.

Limite da regra

É informativa. Não deve executar contestação/cancelamento apenas porque o usuário disse que não reconhece algo.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_invoice_explanation	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	150	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Explicação, composição, diferença, aumento, variação, dúvida ou não reconhecimento informativo de valores/itens de uma fatura já conhecida. Use esta intent quando o cliente estiver tentando entender uma cobrança ou disser que não reconhece itens/valores, mas ainda não pedir explicitamente contestação, cancelamento, estorno, ajuste ou retirada. Não use para fragmentos que apenas mencionem cobrança sem um objeto/referente recuperável; nesses casos solicite clarificação via contas_no_match.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	invoice_explanation	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	explicar fatura explique minha fatura entender minha fatura entender minha conta fatura veio alta conta veio alta veio mais cara conta subiu minha conta subiu fatura subiu minha fatura subiu conta aumentou minha conta aumentou fatura aumentou minha fatura aumentou valor aumentou diferença de valor divergência na fatura divergencia na fatura não entendi a cobrança nao entendi a cobranca por que cobraram por que veio esse valor composição da fatura composicao da fatura detalhar cobrança detalhar cobranca não estou reconhecendo nao estou reconhecendo não reconheço esses itens nao reconheco esses itens itens que não reconheço itens que nao reconheco cobranças que não reconheço cobrancas que nao reconheco	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Contratamos um plano, mas eu não estou reconhecendo esses itens eventuais. Tem cobranças que eu não reconheço e quero entender de onde vieram. Minha fatura veio mais alta e quero entender o que mudou. Quero entender minha conta Por que esse valor mudou? Explique essas cobranças da minha fatura Por que minha conta aumentou este mês?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: explicar fatura, explique minha fatura, entender minha fatura, entender minha conta, fatura veio alta, conta veio alta, veio mais cara, conta subiu.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 150 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Contratamos um plano, mas eu não estou reconhecendo esses itens eventuais., Tem cobranças que eu não reconheço e quero entender de onde vieram., Minha fatura veio mais alta e quero entender o que mudou. entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['invoice_explanation']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool invoice_explanation

O que faz: Explica composição, diferença ou variação de valores de uma fatura; não deve ser usada apenas para consultar/obter a fatura.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna evidências (complete_invoices, billing_analysis, invoice_detail, período/valor/emissão) e uma instrução para o LLM explicar sem inventar cobranças.

Workflow(s): workflows/invoice_explanation.v2.yaml.

Workflows envolvidos

Workflow invoice_explanation.v2.yaml

Nome lógico: invoice_explanation · versão: 2 · start: preparar

Por que existe dessa forma: Foi construído como workflow conversacional porque a explicação não termina na primeira resposta: o agente apresenta a composição, pausa para saber se a explicação resolveu, pode registrar aceite, detectar nova intenção/variação VAS e preparar handoff para outra regra.

Nós

Nó	Action Python	Papel	Pause/Resume
preparar	preparar_invoice_explanation	Executa preparar_invoice_explanation. É o ponto inicial.	não
formatar	formatar_invoice_explanation	Executa formatar_invoice_explanation.	sim; return_from=$.output.mensagem; resposta em resposta_usuario; permitidos=['SIM', 'NAO', 'CONTINUAR']; resume_from=decisao
checar_tentativa	checar_tentativa_cvn	Executa checar_tentativa_cvn.	não
texto_intencao_invalida	montar_resposta_texto	Executa montar_resposta_texto.	não
fim_intencao_invalida	montar_resposta_texto	Executa montar_resposta_texto.	não
resposta_falha_servico	montar_resposta_texto	Executa montar_resposta_texto.	não
decisao	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não
registrar_sim	registrar_atendimento_invoice_explanation	Executa registrar_atendimento_invoice_explanation.	não
registrar_protocolo_aceite	registrar_protocolo_inicio	Executa registrar_protocolo_inicio.	não
registrar_nao	registrar_atendimento_invoice_explanation	Executa registrar_atendimento_invoice_explanation.	não
handoff_pos_explicacao_nao	preparar_handoff_invoice_explanation	Executa preparar_handoff_invoice_explanation.	não
checar_vas_variacao	checar_vas_variado	Executa checar_vas_variado.	não
finalizar_nao_resolvido	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
preparar	formatar	10	{"eq": ["$.vars.preparar.success", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
preparar	resposta_falha_servico	20	{"eq": ["$.vars.preparar.service_failed", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
preparar	checar_tentativa	30	{"eq": ["$.vars.preparar.success", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_tentativa	fim_intencao_invalida	10	{"eq": ["$.vars.checar_tentativa.limite_excedido", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_tentativa	texto_intencao_invalida	20	sempre	Transição incondicional.
formatar	decisao	—	sempre	Transição incondicional.
decisao	registrar_sim	10	{"eq": ["$.input.resposta_usuario", "SIM"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao	registrar_nao	20	{"eq": ["$.input.resposta_usuario", "NAO"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
registrar_sim	registrar_protocolo_aceite	—	sempre	Transição incondicional.
registrar_protocolo_aceite	END	—	sempre	Transição incondicional.
registrar_nao	handoff_pos_explicacao_nao	—	sempre	Transição incondicional.
handoff_pos_explicacao_nao	END	—	sempre	Transição incondicional.
checar_vas_variacao	finalizar_nao_resolvido	10	{"eq": ["$.vars.checar_vas_variacao.tem_vas_variado", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_vas_variacao	END	20	sempre	Transição incondicional.
finalizar_nao_resolvido	END	—	sempre	Transição incondicional.
texto_intencao_invalida	END	—	sempre	Transição incondicional.
fim_intencao_invalida	END	—	sempre	Transição incondicional.
resposta_falha_servico	END	—	sempre	Transição incondicional.

Como funciona a pausa e o resume

• Em formatar, a execução pausa quando null é verdadeira. A mensagem devolvida ao cliente vem de $.output.mensagem. O runtime persiste workflow_name e execution_id; a próxima fala é normalizada no campo resposta_usuario e a execução retorna em decisao. Valores esperados: ['SIM', 'NAO', 'CONTINUAR'].

Término

• O fluxo termina após registrar_protocolo_aceite quando a transição final é alcançada.
• O fluxo termina após handoff_pos_explicacao_nao quando a transição final é alcançada.
• O fluxo termina após checar_vas_variacao quando a transição final é alcançada.
• O fluxo termina após finalizar_nao_resolvido quando a transição final é alcançada.
• O fluxo termina após texto_intencao_invalida quando a transição final é alcançada.
• O fluxo termina após fim_intencao_invalida quando a transição final é alcançada.
• O fluxo termina após resposta_falha_servico quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_invoice_explanation e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.
• app/domain/contas/invoice_resolver.py e parsers: resolução canônica/classificação de itens de fatura.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

Diagnóstico especial — por que a explicação pode levar a outra regra

invoice_explanation.v2 foi construído para não “engolir” a conversa depois de explicar a fatura. Após apresentar a evidência, ele pode pausar, receber a avaliação do cliente e preparar um handoff. Por isso uma frase posterior como “é a de R$ 14,99” pode deixar de ser uma simples explicação e fornecer o parâmetro que faltava para uma contestação; da mesma forma, a identificação de um VAS pode alimentar um fluxo de cancelamento/tratamento.

9. Regra — Contestação de Cobrança

Intent: contas_contestation
Agente: contestacao_agent
Domínio: telecom_contas
Prioridade: 120

O que esta regra significa

Pedido transacional de contestação, estorno, ajuste, retirada ou correção de uma cobrança. Na primeira fala de não reconhecimento sem alvo concreto, use contas_invoice_explanation. Porém, numa reentrada contextual após a explicação, se o pedido original era não reconhecimento e o cliente identificar inequivocamente a cobrança/item/valor que continua questionando, trate a solicitação como contestação daquele alvo; a execução continua sujeita a validação e confirmação transacional.

Limite da regra

É transacional. Precisa haver intenção de contestar/estornar/ajustar/retirar e um alvo suficientemente resolvido.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_contestation	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	contestacao_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	120	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Pedido transacional de contestação, estorno, ajuste, retirada ou correção de uma cobrança. Na primeira fala de não reconhecimento sem alvo concreto, use contas_invoice_explanation. Porém, numa reentrada contextual após a explicação, se o pedido original era não reconhecimento e o cliente identificar inequivocamente a cobrança/item/valor que continua questionando, trate a solicitação como contestação daquele alvo; a execução continua sujeita a validação e confirmação transacional.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_faturas invoice_explanation contestar_cobranca	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	quero contestar quero contestação quero contestacao contestar essa cobrança contestar essa cobranca abrir contestação abrir contestacao quero estorno pedir estorno quero ajuste na fatura ajustar essa cobrança ajustar essa cobranca retirar essa cobrança retirar essa cobranca tirar essa cobrança tirar essa cobranca	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Contexto anterior: cliente não reconhece uma cobrança; após a explicação identifica 'é a de quatorze e noventa e nove'. Após a explicação da fatura, o cliente identifica pelo nome ou valor qual cobrança continua não reconhecendo. Quero contestar essa cobrança Quero abrir uma contestação para esse valor Quero um estorno dessa cobrança Não reconheço essa cobrança e quero contestar Esse valor está errado e quero um ajuste na fatura	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: quero contestar, quero contestação, quero contestacao, contestar essa cobrança, contestar essa cobranca, abrir contestação, abrir contestacao, quero estorno.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 120 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Contexto anterior: cliente não reconhece uma cobrança; após a explicação identifica 'é a de quatorze e noventa e nove'., Após a explicação da fatura, o cliente identifica pelo nome ou valor qual cobrança continua não reconhecendo., Quero contestar essa cobrança entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=contestacao_agent e mcp_tools=['consultar_faturas', 'invoice_explanation', 'contestar_cobranca']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_faturas

O que faz: Consulta faturas atuais/anteriores, status, vencimento, valor e existência de fatura aberta sem iniciar o workflow de explicação.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o payload de faturas e, quando disponível no contexto enriquecido, invoice_amount, invoice_amount_open, invoice_period, invoice_emissao, invoice_id e customer_id.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Tool invoice_explanation

O que faz: Explica composição, diferença ou variação de valores de uma fatura; não deve ser usada apenas para consultar/obter a fatura.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna evidências (complete_invoices, billing_analysis, invoice_detail, período/valor/emissão) e uma instrução para o LLM explicar sem inventar cobranças.

Workflow(s): workflows/invoice_explanation.v2.yaml.

Tool contestar_cobranca

O que faz: Executa contestação no novo domínio Contas após confirmação transacional do framework.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	action
operation_type	transactional
require_confirmation	True
parâmetros obrigatórios pela policy	subject, valor
pre-validation	validar_contestacao (fail_open=False)

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
subject	string	extraído de message via llm	Referência a um item concreto e identificável da fatura (serviço, produto, plano, cobrança específica ou benefício). Uma referência genérica ao documento ou à cobrança como um todo não identifica o subject; quando não houver entidade concreta suficiente para resolução contra a evidência da fatura, mantenha subject ausente/null.
valor	number	extraído de message via llm	Valor monetário explicitamente associado pelo cliente ao item, cobrança ou operação. Se não houver valor explícito ou houver dúvida razoável, manter ausente/null.
motivo	string	extraído de message via llm	Motivo informado pelo cliente para a solicitação ou contestação. Não inventar motivo quando não estiver explícito.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Extração conversacional:

• subject: Extraia o nome do serviço/item cuja cobrança será contestada. Estratégia: llm.
• valor: Extraia o valor monetário explicitamente associado ao item. Retorne null se não houver valor. Estratégia: llm.
• motivo: Extraia o motivo da contestação em frase curta; null se não informado. Estratégia: llm.

Retorno esperado: Retorna success, protocolo, resultado da contestação, tracking e evidências auxiliares de fatura/contrato/perfil.

Workflow(s): workflows/contestacao_tool.v2.yaml.

Workflows envolvidos

Workflow invoice_explanation.v2.yaml

Nome lógico: invoice_explanation · versão: 2 · start: preparar

Por que existe dessa forma: Foi construído como workflow conversacional porque a explicação não termina na primeira resposta: o agente apresenta a composição, pausa para saber se a explicação resolveu, pode registrar aceite, detectar nova intenção/variação VAS e preparar handoff para outra regra.

Nós

Nó	Action Python	Papel	Pause/Resume
preparar	preparar_invoice_explanation	Executa preparar_invoice_explanation. É o ponto inicial.	não
formatar	formatar_invoice_explanation	Executa formatar_invoice_explanation.	sim; return_from=$.output.mensagem; resposta em resposta_usuario; permitidos=['SIM', 'NAO', 'CONTINUAR']; resume_from=decisao
checar_tentativa	checar_tentativa_cvn	Executa checar_tentativa_cvn.	não
texto_intencao_invalida	montar_resposta_texto	Executa montar_resposta_texto.	não
fim_intencao_invalida	montar_resposta_texto	Executa montar_resposta_texto.	não
resposta_falha_servico	montar_resposta_texto	Executa montar_resposta_texto.	não
decisao	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não
registrar_sim	registrar_atendimento_invoice_explanation	Executa registrar_atendimento_invoice_explanation.	não
registrar_protocolo_aceite	registrar_protocolo_inicio	Executa registrar_protocolo_inicio.	não
registrar_nao	registrar_atendimento_invoice_explanation	Executa registrar_atendimento_invoice_explanation.	não
handoff_pos_explicacao_nao	preparar_handoff_invoice_explanation	Executa preparar_handoff_invoice_explanation.	não
checar_vas_variacao	checar_vas_variado	Executa checar_vas_variado.	não
finalizar_nao_resolvido	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
preparar	formatar	10	{"eq": ["$.vars.preparar.success", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
preparar	resposta_falha_servico	20	{"eq": ["$.vars.preparar.service_failed", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
preparar	checar_tentativa	30	{"eq": ["$.vars.preparar.success", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_tentativa	fim_intencao_invalida	10	{"eq": ["$.vars.checar_tentativa.limite_excedido", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_tentativa	texto_intencao_invalida	20	sempre	Transição incondicional.
formatar	decisao	—	sempre	Transição incondicional.
decisao	registrar_sim	10	{"eq": ["$.input.resposta_usuario", "SIM"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao	registrar_nao	20	{"eq": ["$.input.resposta_usuario", "NAO"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
registrar_sim	registrar_protocolo_aceite	—	sempre	Transição incondicional.
registrar_protocolo_aceite	END	—	sempre	Transição incondicional.
registrar_nao	handoff_pos_explicacao_nao	—	sempre	Transição incondicional.
handoff_pos_explicacao_nao	END	—	sempre	Transição incondicional.
checar_vas_variacao	finalizar_nao_resolvido	10	{"eq": ["$.vars.checar_vas_variacao.tem_vas_variado", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
checar_vas_variacao	END	20	sempre	Transição incondicional.
finalizar_nao_resolvido	END	—	sempre	Transição incondicional.
texto_intencao_invalida	END	—	sempre	Transição incondicional.
fim_intencao_invalida	END	—	sempre	Transição incondicional.
resposta_falha_servico	END	—	sempre	Transição incondicional.

Como funciona a pausa e o resume

• Em formatar, a execução pausa quando null é verdadeira. A mensagem devolvida ao cliente vem de $.output.mensagem. O runtime persiste workflow_name e execution_id; a próxima fala é normalizada no campo resposta_usuario e a execução retorna em decisao. Valores esperados: ['SIM', 'NAO', 'CONTINUAR'].

Término

• O fluxo termina após registrar_protocolo_aceite quando a transição final é alcançada.
• O fluxo termina após handoff_pos_explicacao_nao quando a transição final é alcançada.
• O fluxo termina após checar_vas_variacao quando a transição final é alcançada.
• O fluxo termina após finalizar_nao_resolvido quando a transição final é alcançada.
• O fluxo termina após texto_intencao_invalida quando a transição final é alcançada.
• O fluxo termina após fim_intencao_invalida quando a transição final é alcançada.
• O fluxo termina após resposta_falha_servico quando a transição final é alcançada.

Workflow contestacao_tool.v2.yaml

Nome lógico: contestacao_tool · versão: 2 · start: registrar_protocolo

Por que existe dessa forma: Foi separado da conversa porque contestação produz efeitos externos e exige uma sequência auditável: protocolo, validação de status, abertura da contestação, SMS/contrato/SR e atualização de status. A confirmação é feita antes pelo runtime; o workflow recebe uma operação já confirmada.

Nós

Nó	Action Python	Papel	Pause/Resume
registrar_protocolo	registrar_protocolo	Executa registrar_protocolo. É o ponto inicial.	não
enviar_sms	enviar_sms	Executa enviar_sms.	não
check_invoice_status	check_invoice_status	Executa check_invoice_status.	não
abrir_contestacao_cliente	abrir_contestacao_cliente	Executa abrir_contestacao_cliente.	não
consultar_contrato_corte	consultar_contrato_corte	Executa consultar_contrato_corte.	não
abrir_sr_conta_certa_manual	abrir_sr_conta_certa_manual	Executa abrir_sr_conta_certa_manual.	não
atualizar_status_sr	atualizar_status_sr	Executa atualizar_status_sr.	não
atualizar_status_sr_registro	atualizar_status_sr	Executa atualizar_status_sr.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
registrar_protocolo	check_invoice_status	—	sempre	Transição incondicional.
check_invoice_status	abrir_contestacao_cliente	10	sempre	Transição incondicional.
abrir_contestacao_cliente	END	1	{"eq": ["$.vars.abrir_contestacao_cliente.success", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
abrir_contestacao_cliente	enviar_sms	10	{"all": [{"exists": "$.vars.abrir_contestacao_cliente.barcode"}, {"neq": ["$.vars.abrir_contestacao_cliente.barcode", ""]}]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
abrir_contestacao_cliente	consultar_contrato_corte	99	sempre	Transição incondicional.
enviar_sms	consultar_contrato_corte	—	sempre	Transição incondicional.
consultar_contrato_corte	abrir_sr_conta_certa_manual	10	{"any": [{"all": [{"eq": ["$.vars.consultar_contrato_corte.apos_data_corte", true]}, {"eq": ["$.vars.consultar_contrato_corte.contestation_success", true]}, {"any": [{"eq": ["$.input.manual_conta_certa_indicator", true]}, {"eq": ["$.vars.abrir_contestacao_cliente.manual_conta_certa_indicator", true]}]}]}, {"all": [{"eq": ["$.vars.consultar_contrato_corte.dependent_invoice_item", true]}, {"eq": ["$.vars.consultar_contrato_corte.contestation_registered", true]}]}]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
consultar_contrato_corte	atualizar_status_sr	99	sempre	Transição incondicional.
abrir_sr_conta_certa_manual	atualizar_status_sr_registro	10	sempre	Transição incondicional.
atualizar_status_sr_registro	END	—	sempre	Transição incondicional.
atualizar_status_sr	END	—	sempre	Transição incondicional.

Término

• O fluxo termina após abrir_contestacao_cliente quando a condição {"eq": ["$.vars.abrir_contestacao_cliente.success", false]}.
• O fluxo termina após atualizar_status_sr_registro quando a transição final é alcançada.
• O fluxo termina após atualizar_status_sr quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_contestation e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.
• app/domain/contas/invoice_resolver.py e parsers: resolução canônica/classificação de itens de fatura.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Contestação: TIM_PROTOCOL_*, TIM_CUSTOMER_CONTESTATION_*, TIM_TRACKING_ACTIVITIES_*, TIM_SMS_*, TIM_CONTRATO_*, TIM_PROFILE_FULL_AUTH e defaults de canal/client id.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

Diagnóstico especial — “não reconheço” não é automaticamente contestação

O agente diferencia entender de executar uma contestação. Uma primeira fala como “não reconheço essa cobrança” pode cair em contas_invoice_explanation, pois ainda não existe pedido inequívoco de estorno/ajuste/contestação. Depois que a fatura é explicada, se o cliente identifica o alvo — por nome ou valor — e manifesta que continua questionando/quer contestar, o contexto pode reentrar em contas_contestation.

Essa separação existe para não disparar uma transação financeira a partir de uma dúvida informativa. contestar_cobranca exige subject e valor, passa por validar_contestacao, pede confirmação e só depois executa o workflow transacional.

10. Regra — Cancelamento de VAS

Intent: contas_vas_cancel
Agente: contestacao_agent
Domínio: telecom_contas
Prioridade: 145

O que esta regra significa

Cancelamento ou retirada explicitamente solicitada de serviço/VAS. Não use para simples alegação de contratação ou cobrança não reconhecida sem pedido de ação; nesses casos use contas_invoice_explanation.

Limite da regra

A intent significa que o cliente quer cancelar; não garante que o item seja tecnicamente cancelável como VAS avulso. A classe autoritativa do item é verificada depois.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_vas_cancel	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	contestacao_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	145	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Cancelamento ou retirada explicitamente solicitada de serviço/VAS. Não use para simples alegação de contratação ou cobrança não reconhecida sem pedido de ação; nesses casos use contas_invoice_explanation.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_vas cancelar_vas_avulso	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	quero cancelar cancelar meu cancela o cancele o cancelar serviço cancelar servico cancelar assinatura retirar serviço retirar servico desativar serviço desativar servico tirar esse vas	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Quero cancelar esse serviço Quero retirar essa assinatura	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: quero cancelar, cancelar meu, cancela o, cancele o, cancelar serviço, cancelar servico, cancelar assinatura, retirar serviço.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 145 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Quero cancelar esse serviço, Quero retirar essa assinatura entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=contestacao_agent e mcp_tools=['consultar_vas', 'cancelar_vas_avulso']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_vas

O que faz: Consulta serviços VAS ativos.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o catálogo de VAS ativos fornecido pela integração TIM.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Tool cancelar_vas_avulso

O que faz: Executa cancelamento de VAS avulso no novo domínio Contas; confirmação e estado são do framework.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	action
operation_type	transactional
require_confirmation	True
parâmetros obrigatórios pela policy	subject
pre-validation	validar_vas_subject (fail_open=False)

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
subject	string	extraído de message via llm	Referência a um ou mais serviços, produtos ou benefícios concretos e identificáveis nas evidências VAS/fatura do cliente. Preserve referências múltiplas e anafóricas quando o contexto imediato as resolver (por exemplo, "os dois", "ambos", "Netflix e HBO", "todos os VAS avulsos"). Categorias genéricas sem foco conversacional não identificam entidade; se o texto e o contexto não permitirem resolução segura para um item real nas evidências autorizadas, mantenha subject ausente/null.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Extração conversacional:

• subject: Extraia somente o nome do serviço que o cliente quer cancelar. Retorne null se não estiver claro. Estratégia: llm.

Retorno esperado: Retorna success; serviço resolvido; evidência usada (active/history); resultado de bloqueio e cancelamento. Em falha retorna reason como service_not_found, already_inactive_or_blocked, block_vas_failed ou cancel_vas_failed.

Workflow(s): workflows/cancelamento_vas_avulso.v1.yaml.

Workflows envolvidos

Workflow cancelamento_vas_avulso.v1.yaml

Nome lógico: cancelamento_vas_avulso · versão: 1 · start: cancelar_vas_avulso

Por que existe dessa forma: É propositalmente curto: a complexidade de elegibilidade e confirmação fica antes da execução. Quando o workflow começa, os itens já devem estar canônicos e confirmados; a action batch executa bloqueio/cancelamento e tratamento composto por item.

Nós

Nó	Action Python	Papel	Pause/Resume
cancelar_vas_avulso	cancelamento_vas_avulso_batch	Executa cancelamento_vas_avulso_batch. É o ponto inicial.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
cancelar_vas_avulso	END	—	sempre	Transição incondicional.

Término

• O fluxo termina após cancelar_vas_avulso quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_vas_cancel e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.
• app/domain/contas/invoice_resolver.py e parsers: resolução canônica/classificação de itens de fatura.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• VAS: endpoints/credenciais de consulta, histórico, bloqueio/cancelamento e defaults TIM; entre as variáveis presentes no cliente estão TIM_VAS_HISTORY_URL, TIM_VAS_HISTORY_AUTH, TIM_VAS_HISTORY_TIMEOUT e configuração de gateway.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

Diagnóstico especial — por que Tamboro e Paramount+ podem seguir caminhos diferentes

Esta é uma regra crítica do agente. A frase “quero cancelar Tamboro e Paramount+” pode inicialmente ser reconhecida como contas_vas_cancel, porque o objetivo do usuário é cancelar serviços. Isso não significa que todos os itens serão executados pela mesma tool.

A decisão ocorre em duas camadas:

1. Roteamento conversacional: routing.yaml decide que existe um pedido de cancelamento e entrega consultar_vas + cancelar_vas_avulso.
2. Classificação autoritativa de cada entidade: antes de executar, validar_vas_subject/invoice_resolver confronta o nome canônico com a fatura. O método _classify() dá precedência a entry.estrategico, entry.classe e depois à seção da fatura.
   • avulso → cancelar_vas_avulso;
   • estrategico ou bundle → vas_estrategico / tratar_vas_estrategico.

No código, _build_item() define tool_category="vas_estrategico" quando item_type é bundle ou estrategico. No pre-validator MCP, se a tool solicitada era cancelar_vas_avulso mas a entidade resolvida é estratégica, effective_tool muda para tratar_vas_estrategico e a decisão informa action_changed.

Tamboro normalmente permanece no caminho avulso quando a evidência da fatura o classifica assim. O workflow cancelamento_vas_avulso.v1 então executa a action batch de cancelamento.

Paramount+ pode aparecer em seção/registro classificado como estratégico. Nesse caso o domínio impede que ele seja cancelado como se fosse um VAS avulso e o direciona para vas_estrategico.v3, que é um fluxo de explicação/orientação e não um cancelamento técnico automático.

Há ainda um caso de pedido misto já coberto pelos testes: quando múltiplas entidades canônicas foram pré-validadas em items[], o preflight não deve tentar resolver novamente a string agregada "Tamboro Mensal, Paramount+". O snapshot preserva os itens. Na execução batch, cada resultado pode ser diferente — por exemplo, Tamboro com success=true e Paramount+ com success=false/reason=service_not_found; a resposta final deve preservar os dois resultados, sem afirmar que ambos foram cancelados.

Onde olhar ao depurar este comportamento

• config/routing.yaml → contas_vas_cancel e contas_vas_strategic;
• config/tool_policies.yaml → cancelar_vas_avulso.pre_validation.tool=validar_vas_subject;
• config/mcp_parameter_mapping.yaml → extração de subject;
• app/domain/contas/parsers/bill_processor.py → carimbo estrategico;
• app/domain/contas/invoice_resolver.py → _classify() e _build_item();
• contas_mcp/servers/contas_mcp_server/main.py → _validate_vas_subject() e troca de effective_tool;
• workflows/cancelamento_vas_avulso.v1.yaml;
• workflows/vas_estrategico.v3.yaml;
• tests/migration/test_subject_entity_resolution_all_domains.py;
• tests/migration/test_tim_aoferta_transaction_continuation.py.

Esse mecanismo deve ser lido como proteção de semântica de negócio: a intent descreve o que o cliente quer; a classificação de domínio decide qual operação é legal/correta para cada item.

11. Regra — VAS Estratégico / Bundle

Intent: contas_vas_strategic
Agente: contestacao_agent
Domínio: telecom_contas
Prioridade: 125

O que esta regra significa

Tratamento de serviço estratégico, parceiro ou benefício incluso com fluxo específico.

Limite da regra

Representa tratamento específico de estratégico/bundle. Não é sinônimo de cancelamento técnico automático.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_vas_strategic	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	contestacao_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	125	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Tratamento de serviço estratégico, parceiro ou benefício incluso com fluxo específico.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_vas tratar_vas_estrategico	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	apple music deezer disney disney+ netflix youtube premium globoplay amazon prime prime video serviço estratégico servico estrategico benefício incluso beneficio incluso	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Não reconheço o Netflix Quero tratar esse serviço estratégico Meu plano inclui Deezer?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: apple music, deezer, disney, disney+, netflix, youtube premium, globoplay, amazon prime.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 125 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Não reconheço o Netflix, Quero tratar esse serviço estratégico, Meu plano inclui Deezer? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=contestacao_agent e mcp_tools=['consultar_vas', 'tratar_vas_estrategico']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_vas

O que faz: Consulta serviços VAS ativos.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o catálogo de VAS ativos fornecido pela integração TIM.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Tool tratar_vas_estrategico

O que faz: Trata VAS estratégico/bundle no novo domínio Contas; diálogo e estado são do framework.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	conversational
operation_type	conversational
require_confirmation	False
parâmetros obrigatórios pela policy	subject
pre-validation	validar_vas_subject (fail_open=False)

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
subject	string	extraído de message via llm	Referência a um serviço, produto ou benefício concreto e identificável nas evidências VAS/fatura do cliente. Categorias ou referências genéricas não identificam uma entidade por si só; se o texto não permitir resolver univocamente para um item real, mantenha subject ausente/null.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Extração conversacional:

• subject: Extraia somente o nome do serviço estratégico ou incluso citado pelo cliente. Estratégia: llm.

Retorno esperado: Retorna serviço estratégico encontrado, accepted_explanation e orientação de tratamento. Não executa cancelamento automático de VAS estratégico/bundle.

Workflow(s): workflows/vas_estrategico.v3.yaml.

Workflows envolvidos

Workflow vas_estrategico.v3.yaml

Nome lógico: vas_estrategico · versão: 3 · start: preparar

Por que existe dessa forma: Existe porque estratégico/bundle não é equivalente a VAS avulso. O fluxo primeiro explica/trata o serviço, pode pausar aguardando aceite e escolhe caminhos distintos para estratégico e bundle. Ele evita que uma solicitação genérica de 'cancelar' seja transformada automaticamente em cancelamento técnico.

Nós

Nó	Action Python	Papel	Pause/Resume
preparar	preparar_vas_estrategico	Executa preparar_vas_estrategico. É o ponto inicial.	sim; return_from=$.output.mensagem; resposta em resposta_usuario; permitidos=['SIM', 'NAO', 'OUTRO']; resume_from=decisao
resposta_bundle	montar_resposta_texto	Executa montar_resposta_texto.	não
decisao	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não
resposta_sim	montar_resposta_texto	Executa montar_resposta_texto.	não
explicar_cancelamento	montar_explicacao_cancelamento_vas_estrategico	Executa montar_explicacao_cancelamento_vas_estrategico.	não
registrar_sim	registrar_atendimento_vas_estrategico	Executa registrar_atendimento_vas_estrategico.	não
registrar_nao	registrar_atendimento_vas_estrategico	Executa registrar_atendimento_vas_estrategico.	não
registrar_bundle	registrar_atendimento_vas_estrategico	Executa registrar_atendimento_vas_estrategico.	não
registrar_outro	registrar_atendimento_vas_estrategico	Executa registrar_atendimento_vas_estrategico.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
preparar	decisao	10	{"eq": ["$.vars.preparar.await_user_input", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
preparar	resposta_bundle	20	sempre	Transição incondicional.
decisao	resposta_sim	10	{"eq": ["$.input.resposta_usuario", "SIM"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao	explicar_cancelamento	20	{"all": [{"eq": ["$.vars.preparar.has_estrategico_items", true]}, {"eq": ["$.input.resposta_usuario", "NAO"]}]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao	resposta_bundle	30	{"eq": ["$.vars.preparar.has_estrategico_items", false]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao	registrar_outro	99	sempre	Transição incondicional.
resposta_sim	registrar_sim	—	sempre	Transição incondicional.
explicar_cancelamento	registrar_nao	—	sempre	Transição incondicional.
registrar_sim	END	—	sempre	Transição incondicional.
registrar_nao	END	—	sempre	Transição incondicional.
resposta_bundle	registrar_bundle	—	sempre	Transição incondicional.
registrar_bundle	END	—	sempre	Transição incondicional.
registrar_outro	END	—	sempre	Transição incondicional.

Como funciona a pausa e o resume

• Em preparar, a execução pausa quando {"eq": ["$.output.await_user_input", true]} é verdadeira. A mensagem devolvida ao cliente vem de $.output.mensagem. O runtime persiste workflow_name e execution_id; a próxima fala é normalizada no campo resposta_usuario e a execução retorna em decisao. Valores esperados: ['SIM', 'NAO', 'OUTRO'].

Término

• O fluxo termina após registrar_sim quando a transição final é alcançada.
• O fluxo termina após registrar_nao quando a transição final é alcançada.
• O fluxo termina após registrar_bundle quando a transição final é alcançada.
• O fluxo termina após registrar_outro quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_vas_strategic e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.
• app/domain/contas/invoice_resolver.py e parsers: resolução canônica/classificação de itens de fatura.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• VAS: endpoints/credenciais de consulta, histórico, bloqueio/cancelamento e defaults TIM; entre as variáveis presentes no cliente estão TIM_VAS_HISTORY_URL, TIM_VAS_HISTORY_AUTH, TIM_VAS_HISTORY_TIMEOUT e configuração de gateway.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

12. Regra — Consulta de VAS

Intent: contas_vas_information
Agente: vas_agent
Domínio: telecom_contas
Prioridade: 110

O que esta regra significa

Consulta ou explicação de VAS, serviço adicional, assinatura, aplicativo, parceiro, bundle ou benefício adicional. Não use esta intent para perguntas sobre nome, identificação ou valor do plano principal/plano contratado da linha.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_vas_information	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	vas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	110	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Consulta ou explicação de VAS, serviço adicional, assinatura, aplicativo, parceiro, bundle ou benefício adicional. Não use esta intent para perguntas sobre nome, identificação ou valor do plano principal/plano contratado da linha.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_vas	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	vas serviço adicional servico adicional aplicativo assinatura serviços ativos servicos ativos quais são meus serviços quais sao meus servicos meus serviços meus servicos benefício beneficio incluso no plano pacote digital parceiro	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	O que é esse serviço? Quais VAS estão ativos? Esse aplicativo está incluso? Quais serviços adicionais eu tenho?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: vas, serviço adicional, servico adicional, aplicativo, assinatura, serviços ativos, servicos ativos, quais são meus serviços.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 110 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como O que é esse serviço?, Quais VAS estão ativos?, Esse aplicativo está incluso? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=vas_agent e mcp_tools=['consultar_vas']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_vas

O que faz: Consulta serviços VAS ativos.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o catálogo de VAS ativos fornecido pela integração TIM.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_vas_information e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• VAS: endpoints/credenciais de consulta, histórico, bloqueio/cancelamento e defaults TIM; entre as variáveis presentes no cliente estão TIM_VAS_HISTORY_URL, TIM_VAS_HISTORY_AUTH, TIM_VAS_HISTORY_TIMEOUT e configuração de gateway.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

13. Regra — Histórico de VAS

Intent: contas_vas_history
Agente: vas_agent
Domínio: telecom_contas
Prioridade: 105

O que esta regra significa

Consulta de histórico de VAS/serviços que já estiveram ativos ou sofreram alterações.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_vas_history	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	vas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	105	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Consulta de histórico de VAS/serviços que já estiveram ativos ou sofreram alterações.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_historico_vas	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	histórico de vas historico de vas histórico de serviços historico de servicos serviços anteriores servicos anteriores já tive esse serviço ja tive esse servico	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Quero ver meu histórico de serviços Eu já tive esse VAS antes?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: histórico de vas, historico de vas, histórico de serviços, historico de servicos, serviços anteriores, servicos anteriores, já tive esse serviço, ja tive esse servico.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 105 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Quero ver meu histórico de serviços, Eu já tive esse VAS antes? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=vas_agent e mcp_tools=['consultar_historico_vas']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_historico_vas

O que faz: Consulta histórico de serviços VAS.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna histórico de VAS/serviços, usado também como fallback quando um serviço não aparece mais entre os ativos.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_vas_history e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• VAS: endpoints/credenciais de consulta, histórico, bloqueio/cancelamento e defaults TIM; entre as variáveis presentes no cliente estão TIM_VAS_HISTORY_URL, TIM_VAS_HISTORY_AUTH, TIM_VAS_HISTORY_TIMEOUT e configuração de gateway.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

14. Regra — Conhecimento Geral de Contas

Intent: contas_knowledge
Agente: suporte_contas_agent
Domínio: telecom_contas
Prioridade: 120

O que esta regra significa

Perguntas gerais, conceituais, explicativas ou de procedimento sobre funcionamento, tarifação, regras, condições e características de planos, produtos, faturas e serviços que não exigem consultar dados específicos do cliente. Use esta intent quando o usuário perguntar como um plano/produto funciona, mesmo citando seu nome. Não use para descobrir qual plano está contratado na linha nem para consultar valor/dados contratuais do plano atual.

Limite da regra

Serve para conhecimento geral que não requer consultar dados particulares da linha; perguntas sobre 'meu plano/minha fatura' pertencem a intents de dados do cliente.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_knowledge	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	suporte_contas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	120	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Perguntas gerais, conceituais, explicativas ou de procedimento sobre funcionamento, tarifação, regras, condições e características de planos, produtos, faturas e serviços que não exigem consultar dados específicos do cliente. Use esta intent quando o usuário perguntar como um plano/produto funciona, mesmo citando seu nome. Não use para descobrir qual plano está contratado na linha nem para consultar valor/dados contratuais do plano atual.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	—	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	o que é o que significa como funciona como é a tarifação como funciona a tarifação tarifação do plano tarifacao do plano qual a regra quais são as regras quais sao as regras como faço onde encontro informação sobre informacao sobre	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Como funciona o Infinity Pós? Como funciona a tarifação do Infinity Pós? Quais são as regras do Infinity Pós? O que significa cobrança proporcional? Como funciona o vencimento da fatura?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: o que é, o que significa, como funciona, como é a tarifação, como funciona a tarifação, tarifação do plano, tarifacao do plano, qual a regra.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 120 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Como funciona o Infinity Pós?, Como funciona a tarifação do Infinity Pós?, Quais são as regras do Infinity Pós? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=suporte_contas_agent e mcp_tools=[]. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Esta intent não declara MCP tools. O tratamento é conversacional, de clarificação ou de conhecimento por mecanismos do agente/framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_knowledge e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

15. Regra — Status de Solicitação

Intent: contas_service_status
Agente: suporte_contas_agent
Domínio: telecom_contas
Prioridade: 90

O que esta regra significa

Consulta de status, andamento, protocolo ou acompanhamento de solicitação já aberta.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_service_status	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	suporte_contas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	90	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Consulta de status, andamento, protocolo ou acompanhamento de solicitação já aberta.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	consultar_status_solicitacao	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	protocolo status da solicitação status da solicitacao andamento acompanhamento acompanhar solicitação acompanhar solicitacao pedido em andamento	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Qual o status da minha solicitação? Quero acompanhar o protocolo	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: protocolo, status da solicitação, status da solicitacao, andamento, acompanhamento, acompanhar solicitação, acompanhar solicitacao, pedido em andamento.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 90 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Qual o status da minha solicitação?, Quero acompanhar o protocolo entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=suporte_contas_agent e mcp_tools=['consultar_status_solicitacao']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool consultar_status_solicitacao

O que faz: Consulta status de solicitação/protocolo TIM.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.
protocol	string	extraído de message via llm	Número ou identificador de protocolo/solicitação informado pelo cliente ou retornado por sistema.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Extração conversacional:

• protocol: Extraia somente o número de protocolo explicitamente informado pelo cliente; não use message_id ou interaction_key como protocolo. Estratégia: llm.

Retorno esperado: Retorna o status da solicitação/SR consultada pelo protocolo.

Workflow: não há workflow dedicado; a execução é direta no MCP/serviço ou é tratada pelo runtime do framework.

Workflow

Não existe workflow dedicado para esta regra. A capability é executada diretamente ou a resposta é produzida pelo runtime/agente.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_service_status e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.
• app/domain/contas/service.py: regra de domínio e contrato de retorno.
• app/domain/contas/client.py: chamada concreta das integrações TIM.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Solicitação/finalização: TIM_SERVICE_REQUEST_STATUS_*, TIM_DEFAULT_CHANNEL e configuração de protocolo.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

16. Regra — Pró-rata

Intent: contas_pro_rata
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 128

O que esta regra significa

Cobrança proporcional/pró-rata decorrente de troca de plano.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_pro_rata	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	128	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Cobrança proporcional/pró-rata decorrente de troca de plano.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	pro_rata	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	pró-rata pro rata pro-rata cobrança proporcional cobranca proporcional troca de plano	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Por que veio cobrança proporcional? Troquei de plano e vieram duas cobranças	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: pró-rata, pro rata, pro-rata, cobrança proporcional, cobranca proporcional, troca de plano.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 128 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Por que veio cobrança proporcional?, Troquei de plano e vieram duas cobranças entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['pro_rata']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool pro_rata

O que faz: Explica cobrança proporcional e conduz pause/resume pelo WorkflowRuntime.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	conversational
operation_type	conversational
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.
planos	array	fornecido pelo runtime/contexto	Lista de planos identificados no contexto ou retornados por sistemas para análise de pró-rata.
has_plano_controle	boolean	fornecido pelo runtime/contexto	Indicador booleano que informa se há plano Controle entre os planos considerados no fluxo.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna o resultado do workflow conversacional de pró-rata, podendo pausar para esclarecimento.

Workflow(s): workflows/pro_rata.v3.yaml.

Workflows envolvidos

Workflow pro_rata.v3.yaml

Nome lógico: pro_rata · versão: 3 · start: preparar

Por que existe dessa forma: Pró-rata exige explicação e possível esclarecimento do cliente. Por isso o workflow contém pause/resume e caminhos diferentes para plano Controle, aceite e necessidade de repergunta.

Nós

Nó	Action Python	Papel	Pause/Resume
preparar	preparar_pro_rata	Executa preparar_pro_rata. É o ponto inicial.	não
formatar	formatar_pro_rata	Executa formatar_pro_rata.	sim; return_from=$.output.mensagem; resposta em resposta_usuario; permitidos=['SIM', 'NAO', 'OUTRO']; resume_from=decisao_esclarecimento
decisao_esclarecimento	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não
devolver_orquestrador	no_op	Executa no_op. É nó de decisão/orquestração, sem efeito de domínio.	não
reperguntar_esclarecimento	formatar_pro_rata	Executa formatar_pro_rata.	sim; return_from=$.output.mensagem; resposta em resposta_usuario; permitidos=['SIM', 'NAO', 'OUTRO']; resume_from=decisao_esclarecimento
registrar_nao_controle	registrar_atendimento_pro_rata	Executa registrar_atendimento_pro_rata.	não
registrar_aceitou	registrar_atendimento_pro_rata	Executa registrar_atendimento_pro_rata.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
preparar	formatar	—	sempre	Transição incondicional.
formatar	decisao_esclarecimento	10	{"eq": ["$.vars.preparar.await_user_input", true]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
formatar	registrar_nao_controle	20	sempre	Transição incondicional.
decisao_esclarecimento	registrar_aceitou	10	{"eq": ["$.input.resposta_usuario", "SIM"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao_esclarecimento	devolver_orquestrador	20	{"eq": ["$.input.resposta_usuario", "NAO"]}	A transição só ocorre quando a expressão declarativa é verdadeira; quando há várias saídas, o runtime avalia por prioridade crescente.
decisao_esclarecimento	reperguntar_esclarecimento	30	sempre	Transição incondicional.
devolver_orquestrador	END	—	sempre	Transição incondicional.
reperguntar_esclarecimento	decisao_esclarecimento	—	sempre	Transição incondicional.
registrar_nao_controle	END	—	sempre	Transição incondicional.
registrar_aceitou	END	—	sempre	Transição incondicional.

Como funciona a pausa e o resume

• Em formatar, a execução pausa quando {"eq": ["$.vars.preparar.await_user_input", true]} é verdadeira. A mensagem devolvida ao cliente vem de $.output.mensagem. O runtime persiste workflow_name e execution_id; a próxima fala é normalizada no campo resposta_usuario e a execução retorna em decisao_esclarecimento. Valores esperados: ['SIM', 'NAO', 'OUTRO'].
• Em reperguntar_esclarecimento, a execução pausa quando null é verdadeira. A mensagem devolvida ao cliente vem de $.output.mensagem. O runtime persiste workflow_name e execution_id; a próxima fala é normalizada no campo resposta_usuario e a execução retorna em decisao_esclarecimento. Valores esperados: ['SIM', 'NAO', 'OUTRO'].

Término

• O fluxo termina após devolver_orquestrador quando a transição final é alcançada.
• O fluxo termina após registrar_nao_controle quando a transição final é alcançada.
• O fluxo termina após registrar_aceitou quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_pro_rata e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

17. Regra — Término de Desconto

Intent: contas_termino_desconto
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 127

O que esta regra significa

Término de desconto ou promoção refletido na fatura.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_termino_desconto	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	127	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Término de desconto ou promoção refletido na fatura.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	termino_desconto	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	término de desconto termino de desconto desconto acabou fim do desconto	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Meu desconto acabou?	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: término de desconto, termino de desconto, desconto acabou, fim do desconto.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 127 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Meu desconto acabou? entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['termino_desconto']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool termino_desconto

O que faz: Analisa término/retirada de desconto somente com causa suportada por evidência autoritativa.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.
nome_plano	string	extraído de message via llm	Nome do plano ao qual a informação ou tratamento se refere.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Extração conversacional:

• nome_plano: Extraia o nome do plano se explicitamente citado; null se ausente. Estratégia: llm.

Retorno esperado: Retorna resposta formatada a partir de evidência autoritativa sobre o término do desconto.

Workflow(s): workflows/termino_desconto.v1.yaml.

Workflows envolvidos

Workflow termino_desconto.v1.yaml

Nome lógico: termino_desconto · versão: 1 · start: formatar

Por que existe dessa forma: A regra foi reduzida a formatação porque a decisão deve estar apoiada em evidência autoritativa de desconto; o workflow não inventa causa nem cria transação.

Nós

Nó	Action Python	Papel	Pause/Resume
formatar	formatar_capability_resposta	Executa formatar_capability_resposta. É o ponto inicial.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
formatar	END	—	sempre	Transição incondicional.

Término

• O fluxo termina após formatar quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_termino_desconto e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

18. Regra — Valor Divergente

Intent: contas_valor_divergente
Agente: faturas_agent
Domínio: telecom_contas
Prioridade: 126

O que esta regra significa

Capability de valor divergente.

Limite da regra

A regra deve permanecer dentro da descrição declarada; quando o objetivo muda, o roteamento/handoff deve mudar também.

routing.yaml atributo por atributo

Atributo	Valor nesta regra	Como participa da decisão
name	contas_valor_divergente	Identificador estável da intent. É o valor gravado na decisão de roteamento e usado para recuperar tools/agente.
domain	telecom_contas	Domínio lógico. Impede que a intent seja tratada como capability genérica sem contexto de Contas.
agent	faturas_agent	Agente proprietário da conversa depois que a intent é escolhida.
priority	126	Desempate determinístico entre keywords concorrentes. No EnterpriseRouter, menor número vence.
description	Capability de valor divergente.	Definição semântica usada pelo fallback LLM e pela manutenção humana. Deve dizer também quando não usar a intent.
mcp_tools	valor_divergente	Conjunto de tools que o roteamento entrega como capabilities esperadas para esta intent.
keywords	valor divergente divergência de valor divergencia de valor	Gatilhos determinísticos. O router tenta match exato, sequência ordenada de tokens e tokens informativos.
examples	Tem um valor divergente na minha conta	Exemplos fornecidos ao classificador LLM. Não são regex nem são executados diretamente.

Como esta intent é encontrada

1. O router procura primeiro keywords desta regra. Exemplos: valor divergente, divergência de valor, divergencia de valor.
2. Um match pode ser exato ou tolerante a tokens intermediários. Se outra intent também casar, a prioridade 126 participa do desempate.
3. Se o caminho LLM for usado, a descrição acima e exemplos como Tem um valor divergente na minha conta entram no catálogo de classificação.
4. Ao escolher a intent, o router entrega agent=faturas_agent e mcp_tools=['valor_divergente']. O agente não precisa hardcodar esse mapeamento.

Tools desta regra

Tool valor_divergente

O que faz: Trata variação/divergência de valor conforme workflow do Contas.

Propriedade	Valor
MCP server	contas
enabled	True
tool_type	read_only/implícito
operation_type	read_only
require_confirmation	False
parâmetros obrigatórios pela policy	—
pre-validation	—

Dados necessários para chamada

Campo	Tipo	Origem / obtenção	Significado
msisdn	string	mapeado automaticamente de customer_key	Número da linha do cliente (MSISDN) usado para consultar dados associados ao atendimento.

Mapeamento técnico: customer_key → msisdn, session_key → session_id.

Retorno esperado: Retorna resposta formatada pelo workflow de divergência de valor.

Workflow(s): workflows/valor_divergente.v1.yaml.

Workflows envolvidos

Workflow valor_divergente.v1.yaml

Nome lógico: valor_divergente · versão: 1 · start: formatar

Por que existe dessa forma: É um capability workflow simples de apresentação: recebe a evidência preparada pelo domínio e produz a resposta sem efeitos transacionais.

Nós

Nó	Action Python	Papel	Pause/Resume
formatar	formatar_capability_resposta	Executa formatar_capability_resposta. É o ponto inicial.	não

Transições e condições

De	Para	Prioridade	Condição	Interpretação
formatar	END	—	sempre	Transição incondicional.

Término

• O fluxo termina após formatar quando a transição final é alcançada.

Amarração Python

• agent_framework_oci/.../routing/enterprise_router.py: resolve contas_valor_divergente e entrega agente/tools.
• app/agents/runtime.py + runtime do framework: seleção/execução de tools, parâmetros, confirmação e pause/resume.
• contas_mcp/servers/contas_mcp_server/main.py: enriquecimento, preflight, validação e dispatch MCP.

.env e defaults relevantes

• Configuração estrutural: ROUTING_CONFIG_PATH, TOOLS_CONFIG_PATH, TOOL_POLICIES_PATH, MCP_PARAMETER_MAPPING_PATH, MCP_SERVERS_CONFIG_PATH.
• Roteamento: ENABLE_LLM_ROUTER e parâmetros ROUTE_STICKINESS_* quando habilitados.
• Billing/fatura: URLs e timeouts de fatura/PDF definidos no .env e complementados por config/tim_integration_defaults.yaml.
• Resiliência de integração: TIM_GATEWAY_MODE, TIM_GATEWAY_DEFAULT_TIMEOUT, TIM_GATEWAY_RETRY_MAX_RETRIES, TIM_GATEWAY_RETRY_BACKOFF_FACTOR, TIM_USE_MOCK_GATEWAY.

Regras transversais

Confirmação transacional

tool_policies.yaml é a fonte declarativa que diferencia leitura, conversa e transação. cancelar_vas_avulso e contestar_cobranca usam require_confirmation: true. O runtime coleta parâmetros, chama a pre-validation e só então pergunta ao usuário. Uma resposta inequívoca é processada deterministicamente; respostas inconclusivas podem usar o transaction_confirmation.semantic_fallback definido em routing.yaml.

Coleta de parâmetros

Os campos obrigatórios vêm da policy (requires) e do schema da tool. mcp_parameter_mapping.yaml informa o que pode vir automaticamente do contexto e o que deve ser extraído da mensagem. Se um campo obrigatório continuar faltando, a sessão entra em COLLECTING_*_PARAMETERS, e state_policies mantém a fala seguinte no agente proprietário.

Pre-validation

Pre-validation não deve produzir efeito externo. Ela resolve entidade, elegibilidade, valor e classe de negócio. Em VAS, validar_vas_subject pode mudar a tool efetiva. Em contestação, validar_contestacao protege contra item/valor não suportado pela fatura.

Pause/Resume de workflow

Um nó com pause.enabled=true devolve uma mensagem ao cliente e persiste a execução. A próxima fala é entregue ao mesmo workflow por execution_id, normalizada conforme expected_input e retomada em resume_from. retomar_workflow é infraestrutura; não representa uma intent de negócio.

Multi-intent

O MultiIntentPlanner deve separar objetivos independentes, por exemplo “cancelar X e mandar segunda via”. Ele não deve decompor subject, valor e motivo de uma única contestação em intents diferentes. Em pedidos com vários VAS, os itens canônicos permanecem em items[] para evitar reinterpretação da string agregada.

State stickiness

Estados WAITING_*_CONFIRMATION e COLLECTING_*_PARAMETERS têm precedência sobre uma nova classificação de uma fala curta. Mudança explícita de assunto pode liberar handoff conforme as políticas de continuidade/intent shift.

Guia de diagnóstico de uma decisão inesperada

Use esta sequência:

1. Qual era o estado antes da fala? Veja transaction_status, workflow pausado e state_policies.
2. Qual intent foi escolhida e por qual método? state, keyword, LLM ou fallback.
3. Qual keyword venceu? Lembre que menor priority vence e keywords mais específicas desempatarão.
4. Quais tools a intent autorizou?
5. Qual tool o runtime realmente selecionou? Compare selection_keywords, transação ativa e pending topics.
6. Quais parâmetros foram coletados? Diferencie requested_arguments de resolved_arguments.
7. O pre-validator alterou algo? Verifique effective_tool_name, action_changed, domain_policy.class e entidade canônica.
8. Havia múltiplos itens? Se sim, items[] deve ser a fonte de verdade; não re-resolver a string unida.
9. Qual workflow começou? Confira versão ativa e execution_id.
10. Em qual nó/aresta terminou ou pausou? Avalie condições por prioridade.
11. Qual integração falhou? Diferencie erro de classificação, elegibilidade e erro técnico (service_not_found, timeout, backend etc.).
12. A resposta final preservou resultados parciais? Um item bem-sucedido não autoriza afirmar sucesso para os demais.

Exemplo completo — “quero cancelar Tamboro e Paramount+”

Mensagem
  ↓
routing.yaml → contas_vas_cancel
  ↓
tools candidatas: consultar_vas + cancelar_vas_avulso
  ↓
extração de subject / resolução de múltiplas entidades
  ↓
validar_vas_subject / invoice_resolver
  ├─ Tamboro Mensal → avulso → cancelar_vas_avulso
  └─ Paramount+ → estratégico/bundle conforme evidência → tratar_vas_estrategico
  ↓
cada item preserva sua classe e resultado
  ├─ avulso → confirmação → cancelamento_vas_avulso.v1
  └─ estratégico → vas_estrategico.v3 → explicação/orientação/pause-resume

A lição arquitetural é que o verbo do usuário escolhe a intenção, mas a evidência do domínio escolhe a operação válida para a entidade. É exatamente por isso que dois serviços citados na mesma frase podem terminar em regras diferentes.

Arquivos-fonte mais importantes

• config/routing.yaml
• config/tools.yaml
• config/tool_policies.yaml
• config/mcp_parameter_mapping.yaml
• config/agents.yaml
• config/tim_integration_defaults.yaml
• .env.example
• contas_mcp/servers/contas_mcp_server/main.py
• app/domain/contas/invoice_resolver.py
• app/domain/contas/parsers/bill_processor.py
• app/domain/contas/workflow_actions.py
• app/domain/contas/service.py
• app/domain/contas/client.py
• agent_framework_oci/libs/agent_framework/src/agent_framework/routing/enterprise_router.py
• agent_framework_oci/libs/agent_framework/src/agent_framework/runtime/agent_runtime.py
• agent_framework_oci/libs/agent_framework/src/agent_framework/workflows/runtime.py