agent_platform_oci/docs/developer/pt/VALIDATION_README_ALIGNMENT.md

Validação de Alinhamento da Documentação

Objetivo

Registrar como a documentação desta versão foi reorganizada e quais fontes devem ser usadas pelo desenvolvedor.

Decisão estrutural

O README.md da raiz é o único tutorial principal ponta a ponta.

O antigo 01_architecture_and_agent_development.md foi removido porque repetia grande parte do README, mas não todo ele. Isso criava ambiguidade: dois documentos aparentavam ensinar a mesma coisa, porém um era parcial.

A nova estrutura substitui esse arquivo por 01_architecture_and_concepts.md, que contém apenas arquitetura, conceitos, responsabilidades e critérios de extensão.

Validação de README_old2.md

Documentacao/README_old2.md permanece útil como histórico, mas não é fonte principal para desenvolvimento.

Foram encontradas evoluções posteriores no README atual e no código, incluindo:

• SPECs/SDDs;
• configuração mais completa de llm_profiles.yaml;
• Channel Gateway e contratos canônicos;
• memory e summary_memory no ciclo atual do agente;
• prepare_memory_context() e build_messages();
• RuntimeContext;
• normalize_tools_by_intent();
• build_tool_arguments();
• execute_tools_for_intent();
• helpers de estado transacional;
• respostas MCP diretas;
• evolução de gateways, RAG, memória e políticas.

Correção aplicada ao README principal

Foi corrigido no pacote gerado o typo:

from app.agents.financeiro_agent import FinanceirotAgent

para:

from app.agents.financeiro_agent import FinanceiroAgent

A classe correta é confirmada pelo código e pelo restante da documentação.

APIs confirmadas na implementação atual

AgentRuntimeMixin.get_runtime_context()
AgentRuntimeMixin.normalize_tools_by_intent()
AgentRuntimeMixin.build_tool_arguments()
AgentRuntimeMixin.execute_tools_for_intent()
AgentRuntimeMixin.prepare_memory_context()
AgentRuntimeMixin.build_messages()
AgentRuntimeMixin.transaction_state_patch()
AgentRuntimeMixin.transaction_clarification_message()
AgentRuntimeMixin.transaction_confirmation_message()
AgentRuntimeMixin.build_direct_mcp_answer()

Ordem de confiança

1. código da versão;
2. README principal da mesma versão;
3. SPECs/SDDs;
4. manuais especializados;
5. release notes;
6. documentos README_old*.

Regra de manutenção futura

Uma evolução de feature deve atualizar:

1. o README principal, somente se alterar o caminho normal de desenvolvimento;
2. o manual especializado da feature, com detalhes técnicos, comportamento, configuração e troubleshooting;
3. a SPEC, quando houver mudança de contrato;
4. release note, quando for necessário registrar a mudança histórica.

Não crie um novo “manual principal” para uma feature. Não mantenha correções funcionais permanentemente apenas em release notes.