bugfix: Propagação de sessionId no langfuse

libs/agent_framework/docs/LANGFUSE_NATIVE_SESSION_ID_FIX.md

@@ -0,0 +1,62 @@
+# Langfuse native `sessionId` fix
+
+## Problema
+
+O Agent Framework já carregava `session_id` no contexto e no metadata de spans,
+porém traces criados com Langfuse Python SDK v4 podiam aparecer com
+`trace.sessionId = null`. Como consequência, `/api/public/sessions` não retornava
+as conversas, embora `metadata.session_id` estivesse presente nas observations.
+
+## Causa
+
+No Langfuse Python SDK v4, atributos correlacionais como `session_id`, `user_id`,
+tags e metadata devem ser aplicados por `propagate_attributes`, que é uma função
+**de nível de módulo** (`from langfuse import propagate_attributes`).
+
+O framework tinha duas tentativas:
+
+1. `observation.update_trace(session_id=...)` — mantido por compatibilidade, mas
+   descontinuado no SDK v4;
+2. `self.langfuse.propagate_attributes(...)` — formato incompatível com o SDK v4,
+   pois `propagate_attributes` não é método do client.
+
+## Correção
+
+`Telemetry` agora importa e mantém o callable de módulo do Langfuse v4 e o usa
+imediatamente dentro do root span:
+
+```text
+agent.gateway_message root span
+    -> propagate_attributes(
+         session_id=<agent_session_id>,
+         user_id=<user_id>,
+         metadata=<correlation metadata>,
+         tags=<root tags>,
+         trace_name=<root span name>
+       )
+    -> workflow / child observations
+```
+
+O fallback por método do client permanece para compatibilidade com SDKs ou
+wrappers anteriores.
+
+## Resultado esperado
+
+Para uma sessão de negócio:
+
+```text
+default:telecom_contas:f2a6e957-2c74-49ba-882e-ad14131cf1cc
+```
+
+o trace retornado pelo Langfuse deve apresentar:
+
+```json
+{
+  "sessionId": "default:telecom_contas:f2a6e957-2c74-49ba-882e-ad14131cf1cc"
+}
+```
+
+e `/api/public/sessions` deve materializar/agrupar a sessão.
+
+O `session_id` continua também no metadata do framework para diagnóstico e
+retrocompatibilidade.