agent_framework_oci/LOCALIZACAO.md

Termos e frases configuráveis — pt-BR e en

Esta distribuição inclui dois catálogos completos, em JSON UTF-8:

• libs/agent_framework/src/agent_framework/locales/pt-BR.json
• libs/agent_framework/src/agent_framework/locales/en.json

Cada arquivo reúne termos reconhecidos, mensagens padronizadas, instruções de recuperação de guardrails e padrões de extração. JSON permite editar o catálogo sem uma dependência adicional no carregador. Os dois arquivos usam as mesmas chaves.

Selecionar o idioma

No .env do backend:

AGENT_LOCALE=en

Para português, use AGENT_LOCALE=pt-BR ou omita a variável. Também são aceitos pt, pt_BR, en-US e en-GB. Uma opção inexistente gera erro; não há troca silenciosa para português quando o idioma solicitado não está disponível.

O idioma é o padrão do backend. Os prompts e as configurações de negócio dos agentes continuam sendo definidos pelo projeto; use prompts e descrições no idioma desejado. Esta alteração não traduz automaticamente conteúdos de RAG, respostas dos servidores MCP, mensagens declaradas por um workflow, arquivos de exemplo, regras de negócio ou textos personalizados do aplicativo/frontend. Prompts internos de classificação podem continuar em português: as decisões são estruturadas. As instruções de recuperação que impunham português foram separadas nos catálogos, incluindo sua variante em inglês.

Personalizar sem alterar a biblioteca

Copie os catálogos para um diretório da aplicação e configure:

AGENT_LOCALE=en
AGENT_LOCALES_DIR=./config/locales

Nesse exemplo, o arquivo usado será ./config/locales/en.json. O catálogo é completo, e não um arquivo de alterações parciais. Preserve as chaves e os campos como {action}, {target}, {options} e {subject} ao traduzir as frases. Não é necessário manter a mesma quantidade de termos nas listas.

Reinicie o backend após editar os arquivos: o carregador mantém os catálogos em cache. Na inicialização, ele verifica a estrutura, os campos das mensagens, a sintaxe dos padrões e conflitos entre confirmação e recusa.

As principais seções são:

Seção	Conteúdo
terms.confirmation	Confirmações e recusas explícitas de transações
terms.workflow	Respostas de compatibilidade para checkpoints antigos
terms.multi_intent	Conjunções, verbos e prefixos de confirmação
terms.global_router	Termos de continuidade e encerramento
terms.groundedness	Indícios de especificidade e incerteza
terms.mock	Termos dos classificadores locais usados em testes/desenvolvimento
messages	Frases de confirmação, nova tentativa, esclarecimento e fallback
prompts.fallback	Instruções de reescrita e regeneração por guardrail
prompts.judge_rewrite	Instruções de recuperação dos judges
memory	Padrões para extração de memória de longo prazo
protocol	Dígitos, letras e nomes usados na vocalização de protocolos
safety	Padrões determinísticos de segurança e escopo
legacy_extraction	Padrões do extrator legado de pedido/motivo

Decisões internas e contratos de workflow

Os códigos internos permanecem estáveis: confirm, reject, SIM, NAO, OUTRO e nomes de estados não devem ser traduzidos em arquivos existentes. O catálogo trata as palavras reconhecidas e os textos apresentados.

Um workflow que declara expected_input, reprompt ou mensagens próprias continua tendo precedência. Para aceitar YES e NO em um contrato enumerado, configure essas opções no workflow e ajuste suas transições, ou mantenha os códigos atuais e use seu classificador semântico para mapear as respostas. O dicionário global não substitui silenciosamente o contrato de um fluxo.

As listas de confirmação transacional usam correspondência da frase completa, ignorando maiúsculas, espaços repetidos e pontuação final simples. Não inclua frases ambíguas como “entendi”/“understood” nessas listas: compreender uma explicação não equivale a autorizar uma operação. O fallback semântico existente continua disponível para respostas que não constam do catálogo.

Os padrões de segurança mantêm cobertura em português e inglês nos dois arquivos. Nomes de concorrentes presentes em safety preservam a configuração original de telecom; adapte essas regras quando mudar o domínio da aplicação.

Vários idiomas no mesmo processo

Para aplicações que selecionam o idioma por agente ou atendimento, envolva a execução completa (roteamento, runtime e guardrails) no contexto correspondente:

from agent_framework.localization import use_locale

with use_locale("en"):
    # Execute aqui o roteamento, o agente e seus guardrails.
    result = await handle_turn(...)

handle_turn representa o ponto de entrada da sua aplicação; não é uma nova API do framework. O contexto usa ContextVar, é isolado entre tarefas assíncronas e restaura o idioma anterior ao sair. Não altere os.environ a cada atendimento. O idioma da conversa não é detectado automaticamente.

Validação desta entrega

• 41 testes novos de localização aprovados.
• 160 testes selecionados aprovados após a atualização de oito testes antigos.
• As oito expectativas antigas estavam desalinhadas com mudanças de contrato anteriores à localização. Histórico, escopo e validação estão em ATUALIZACAO_TESTES.md. Os 66 testes dos quatro arquivos atualizados também passaram com a biblioteca original do ZIP.
• As verificações incluem execução/cancelamento real do runtime com ferramentas simuladas, confirmação determinística no roteador sem LLM, múltiplas intenções, retomada de workflows, memória, protocolos, segurança, concorrência e catálogo personalizado.
• Não foram feitas chamadas a modelos remotos, OCI ou ferramentas reais de negócio.

Os testes novos estão em tests/test_locale_catalogs.py. Para executá-los em um ambiente com as dependências do projeto e pytest/pytest-asyncio:

PYTHONPATH=libs/agent_framework/src pytest -q tests/test_locale_catalogs.py

O pacote de entrega conserva os arquivos do projeto e remove metadados do macOS, cache de bytecode, builds antigos e diretórios de Git/IDE. As fontes corrigidas ficam em libs/agent_framework/src. As variantes de demonstração em Tuning-Performance mantêm suas configurações de domínio originais.