Ajustes conforme relatorio de testes 2026-08-27

docs/developer/en/11_observability_persistence_and_operational_readiness.md

@@ -200,6 +200,19 @@ request_id → tenant_id → agent_id → session_id → user_id → channel →
 
 The context uses `ContextVar`, so it works across async calls, FastAPI, LangGraph, and LLM providers.
 
+### Langfuse OpenAI auto-instrumentation policy
+
+The official framework template configuration is:
+
+```env
+ENABLE_LANGFUSE=true
+ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=false
+```
+
+The `false` value is intentional. The framework already records model calls through `Telemetry.generation(...)` and keeps each generation inside the request trace. Enabling `langfuse.openai` at the same time adds a second instrumentation layer and may produce standalone `OpenAI-generation` root traces, duplicate observations, and duplicate token/cost accounting.
+
+Use `true` only to capture direct OpenAI/OpenAI-compatible SDK calls that occur outside the framework telemetry layer. This is a compatibility/diagnostic mode, not the operational default. Every `.env.example` in the repository must explicitly keep the value set to `false`.
+
 ### Langfuse
 
 Enable in `.env`:

docs/developer/pt/11_observability_persistence_and_operational_readiness.md

@@ -201,6 +201,19 @@ request_id → tenant_id → agent_id → session_id → user_id → channel →
 
 O contexto usa `ContextVar`, portanto funciona em chamadas assíncronas, FastAPI, LangGraph e providers LLM.
 
+### Política de auto-instrumentação OpenAI no Langfuse
+
+A configuração oficial dos templates do framework é:
+
+```env
+ENABLE_LANGFUSE=true
+ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=false
+```
+
+O `false` é intencional. O framework já registra as chamadas ao modelo usando `Telemetry.generation(...)` e mantém a generation dentro do trace da requisição. Habilitar simultaneamente `langfuse.openai` cria uma segunda camada de instrumentação e pode resultar em `OpenAI-generation` como trace raiz, observations duplicadas e dupla contabilização de tokens/custos.
+
+Use `true` somente para capturar chamadas diretas ao SDK OpenAI/OpenAI-compatible que ocorram fora da telemetria do framework. Esse é um modo de compatibilidade/diagnóstico, não o padrão operacional. Todos os `.env.example` do repositório devem permanecer explicitamente com o valor `false`.
+
 ### Langfuse
 
 Ative no `.env`: