Documentation organization

docs/developer/pt/INDEX_DEVELOPER_GUIDE.md

@@ -0,0 +1,134 @@
+
+### Índice de Desenvolvimento — Agent Framework OCI
+
+### Como usar esta documentação
+
+A documentação possui três níveis claros:
+
+1. **Tutorial principal:** [`README.md`](../../../README.md) — criação, configuração, execução e teste de um agente do início ao fim.
+2. **Arquitetura:** [01 — Arquitetura e Conceitos](./01_architecture_and_concepts.md) — componentes, responsabilidades e onde implementar cada coisa.
+3. **Referências especializadas:** manuais `02` a `11` — implementação profunda e troubleshooting por capacidade.
+
+Se você está começando um novo agente, comece pelo `README.md`.
+
+Se algo não está funcionando, use **Buscar pelo problema** abaixo.
+
+### Buscar pelo problema
+
+| Problema / dúvida | O que normalmente está envolvido | Onde procurar |
+|---|---|---|
+| O framework não encontra o agente/intenção correta | routing, intents, threshold, modo determinístico/LLM | [Routing e Stickiness](./02_routing_stickiness_and_intent_shift.md) |
+| O agente fica preso no mesmo assunto e não troca de intent | route stickiness, intent shift, handoff | [Routing e Stickiness](./02_routing_stickiness_and_intent_shift.md) |
+| Uma resposta que deveria preencher parâmetro é interpretada como novo intent | precedência transacional, parameter extraction | [Workflows Transacionais](./03_transaction_workflows_and_state.md) |
+| A transação fica pedindo o mesmo parâmetro | estado transacional, extractor, schema | [Workflows Transacionais](./03_transaction_workflows_and_state.md) e [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
+| A confirmação “sim/não” não continua o fluxo | confirmation state, transaction state | [Workflows Transacionais](./03_transaction_workflows_and_state.md) |
+| Uma transação encerrada reaparece | checkpoint antigo versus estado transacional ativo | [Workflows Transacionais](./03_transaction_workflows_and_state.md) e [LTM/Checkpoint](./08_long_term_memory_and_checkpoint.md) |
+| O sistema diz que executou algo, mas não existe evidência | MCP result, estado `COMPLETED`, judges transacionais | [Workflows Transacionais](./03_transaction_workflows_and_state.md) e [Guardrails/Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
+| Uma tool não aparece ou não é encontrada | `tools.yaml`, catálogo MCP, discovery | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
+| MCP Server não aparece no catálogo | registration, manifest/discovery, MCP Gateway | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) e [Gateways](./05_agent_gateway_mcp_gateway_and_auth.md) |
+| Parâmetros enviados à tool estão errados | schema, mapping, BusinessContext, extractor | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
+| Uma operação transacional executa sem confirmação | tool policy, `require_confirmation` | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
+| Uma busca por nome exige correspondência exata demais | extração/mapeamento de parâmetros e lógica do agente | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
+| Recebo 401 entre gateway/backend/MCP | Basic Auth, credenciais por hop | [Gateways e Auth](./05_agent_gateway_mcp_gateway_and_auth.md) |
+| Preciso decidir se algo pertence ao framework ou ao agente | boundary core/agente | [Arquitetura e Conceitos](./01_architecture_and_concepts.md) |
+| Guardrail específico de um agente está quebrando outro | extensibilidade, imports de domínio no core | [Guardrails e Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
+| Judge não roda em uma transação | sampling, `always_run_for_transactional`, sinais transacionais | [Guardrails e Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
+| Groundedness está avaliando sem contexto correto | RAG context, MCP evidence, judge inputs | [RAG/Grounding](./07_rag_business_context_and_grounding.md) |
+| RAG não encontra conteúdo | provider, ingestão, embeddings, configuração | [RAG/Grounding](./07_rag_business_context_and_grounding.md) |
+| Não sei se usar RAG, memória ou tool | separação de responsabilidades | [Arquitetura e Conceitos](./01_architecture_and_concepts.md) e [RAG/Grounding](./07_rag_business_context_and_grounding.md) |
+| Memória desaparece ao trocar de sessão | LTM versus conversation memory | [LTM e Checkpoint](./08_long_term_memory_and_checkpoint.md) |
+| Memória de um cliente/agente aparece em outro | identity key, tenant/agent/customer isolation | [LTM e Checkpoint](./08_long_term_memory_and_checkpoint.md) |
+| Preciso recuperar `reasoning_content` | `ainvoke_response()` | [LLM Rich Response](./09_llm_rich_response_reasoning.md) |
+| `reasoning_content` vem `None` | provider/model não expõe o campo | [LLM Rich Response](./09_llm_rich_response_reasoning.md) |
+| Há chamadas LLM desnecessárias | routing determinístico, concorrência, cache | [Performance](./10_performance_cache_and_async_runtime.md) |
+| Há deadlock ou espera entre event loops | cross-loop sequence/runtime | [Performance](./10_performance_cache_and_async_runtime.md) |
+| Logs/traces não correlacionam o mesmo agente | labels, IDs e mapeamento de observabilidade | [Observabilidade](./11_observability_persistence_and_operational_readiness.md) |
+| Sequence está interferindo no processamento | implementação assíncrona de sequência | [Observabilidade](./11_observability_persistence_and_operational_readiness.md) e [Performance](./10_performance_cache_and_async_runtime.md) |
+| Um exemplo antigo não compila | documentação histórica versus API atual | [Validação README x Código](./VALIDATION_README_ALIGNMENT.md) |
+| Preciso criar um agente novo do zero | fluxo completo | [`README.md`](../../../README.md) |
+| Preciso saber onde colocar uma nova feature | arquitetura e boundaries | [Arquitetura e Conceitos](./01_architecture_and_concepts.md) |
+
+### Buscar pela funcionalidade
+
+### [01 — Arquitetura e Conceitos](./01_architecture_and_concepts.md)
+
+**O que é:** visão dos componentes, contratos e limites de responsabilidade.
+
+**Use quando:** precisar entender a plataforma, decidir onde implementar algo ou evitar acoplamento entre core e agente.
+
+### [02 — Routing, Route Stickiness e Intent Shift](./02_routing_stickiness_and_intent_shift.md)
+
+**O que é:** referência completa de descoberta de agente/intent, stickiness, handoff e mudança de intenção.
+
+**Use quando:** a mensagem cai no agente errado, não troca de intent ou perde continuidade.
+
+### [03 — Workflows Transacionais e Estado](./03_transaction_workflows_and_state.md)
+
+**O que é:** ciclo transacional multi-turno, estados, confirmação, pausa/retomada e evidência operacional.
+
+**Use quando:** há loops, confirmações incorretas, retomadas erradas ou operações críticas.
+
+### [04 — MCP, Tools, Policies e Extração de Parâmetros](./04_mcp_integration_tools_and_policies.md)
+
+**O que é:** referência de tools, MCP Servers, mappings, policies e parameter extraction.
+
+**Use quando:** integração/execução de tool está incorreta ou precisa ser criada.
+
+### [05 — Agent Gateway, MCP Gateway e Autenticação](./05_agent_gateway_mcp_gateway_and_auth.md)
+
+**O que é:** responsabilidades dos gateways, governança e autenticação entre componentes.
+
+**Use quando:** houver problema de entrada, catálogo, autorização, 401 ou deployment dos gateways.
+
+### [06 — Guardrails, Judges e Avaliação Transacional](./06_guardrails_judges_and_transaction_evaluation.md)
+
+**O que é:** validações nativas/externas, judges, grounding e regras para turnos transacionais.
+
+**Use quando:** uma validação bloqueia, não roda ou produz avaliação incorreta.
+
+### [07 — RAG, BusinessContext e Grounding](./07_rag_business_context_and_grounding.md)
+
+**O que é:** providers de RAG, contexto recuperado, BusinessContext e grounding.
+
+**Use quando:** conhecimento recuperado não chega corretamente ao agente/judge.
+
+### [08 — Long-Term Memory e Checkpoint](./08_long_term_memory_and_checkpoint.md)
+
+**O que é:** memória durável, memória conversacional, identidade e snapshots de estado.
+
+**Use quando:** contexto some, vaza ou workflow retoma do lugar errado.
+
+### [09 — LLM Rich Response e reasoning_content](./09_llm_rich_response_reasoning.md)
+
+**O que é:** resposta estruturada de inferência além do `str` retornado por `ainvoke()`.
+
+**Use quando:** consumidores precisam de metadados, usage ou reasoning disponibilizado pelo provider.
+
+### [10 — Performance, Cache e Runtime Assíncrono](./10_performance_cache_and_async_runtime.md)
+
+**O que é:** otimizações de concorrência, cache, LLM e event loops.
+
+**Use quando:** houver latência evitável, processamento serial ou deadlock.
+
+### [11 — Observabilidade, Persistência e Prontidão Operacional](./11_observability_persistence_and_operational_readiness.md)
+
+**O que é:** correlação, eventos, labels, sequence, persistência e diagnóstico.
+
+**Use quando:** for necessário provar o caminho executado ou diagnosticar produção.
+
+### Tutorial principal
+
+[`README.md`](../../../README.md) continua sendo a referência para o passo a passo completo:
+
+`arquitetura → configuração → criação do agente → registro → estado → routing → tools → MCP → identidade → execução → testes → gateways → memória → RAG`.
+
+### Manutenção
+
+Não crie outro tutorial paralelo ao `README.md`.
+
+Ao evoluir uma feature:
+
+- atualize o README somente se o fluxo normal de desenvolvimento mudou;
+- atualize o manual especializado com comportamento, configuração, exemplos e troubleshooting;
+- atualize SPECs se o contrato mudou;
+- mantenha release notes como histórico, não como única documentação atual.