feat: implement Phase 1 zero-config observability with --observe langfuse flag

- Add global --observe flag to CLI with PRAISONAI_OBSERVE env var support
- Wire observability automatically into Langflow Agent and Agents components
- Update langfuse_example.py to use current TraceSinkProtocol API
- Graceful degradation when Langfuse not installed

Enables users to run:
- praisonai run workflow.yaml --observe langfuse
- PRAISONAI_OBSERVE=langfuse praisonai flow

Fixes #1364 (Phase 1)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: praisonai-triage-agent[bot]

examples/observability/langfuse_example.py

@@ -1,48 +1,39 @@
 """
-Langfuse Integration Example
+Langfuse Integration Example (Updated for TraceSinkProtocol)
 
-This example shows how to use Langfuse for LLM observability.
+This example shows how to use Langfuse for LLM observability with PraisonAI's native trace infrastructure.
 
 Setup:
-    1. Sign up at https://langfuse.com/
-    2. Get your API keys from the project settings
-    3. Set environment variables:
-       export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
-       export LANGFUSE_SECRET_KEY=sk-lf-xxx
-    4. Install dependencies:
-       pip install opentelemetry-sdk opentelemetry-exporter-otlp
+    pip install "praisonai[langfuse]"
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
 
 Usage:
     python langfuse_example.py
 """
-
-import os
-from praisonai_tools.observability import obs
 from praisonaiagents import Agent
-
-# Initialize Langfuse
-success = obs.init(
-    provider="langfuse",
-    project_name="praisonai-demo",
+from praisonai.observability import LangfuseSink
+from praisonaiagents.trace.context_events import (
+    ContextTraceEmitter, set_context_emitter
 )
 
-if not success:
-    print("Failed to initialize Langfuse. Check your API keys.")
-    print("Required: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY")
-    exit(1)
+# Initialize Langfuse observability
+sink = LangfuseSink()
+emitter = ContextTraceEmitter(sink=sink, enabled=True)
+set_context_emitter(emitter)
 
-print("Langfuse initialized successfully!")
-print(f"View traces at: https://cloud.langfuse.com/")
-
-# Create agent
+# Create and run agent — all traces automatically captured
 agent = Agent(
+    name="Coder",
     instructions="You are a helpful coding assistant.",
-    model="gpt-4o-mini",
+    llm="openai/gpt-4o-mini",
 )
 
-# Run with tracing
-with obs.trace("coding-session", user_id="developer-1"):
-    response = agent.chat("Write a Python function to calculate fibonacci numbers")
-    print(response)
+result = agent.start("Write a Python function to calculate fibonacci numbers")
+print(result)
+
+# Flush traces
+sink.flush()
+sink.close()
 
 print("\nCheck Langfuse dashboard for traces!")

src/praisonai/praisonai/cli/app.py

@@ -13,6 +13,32 @@
 from .state.identifiers import create_context
 
 
+def _setup_langfuse_observability() -> None:
+    """Set up Langfuse observability by wiring TraceSink to both action and context emitters."""
+    try:
+        from praisonai.observability.langfuse import LangfuseSink
+        from praisonaiagents.trace.protocol import TraceEmitter, set_default_emitter
+        from praisonaiagents.trace.context_events import ContextTraceEmitter, set_context_emitter
+        
+        # Create LangfuseSink (auto-reads env vars)
+        sink = LangfuseSink()
+        
+        # Set up action-level trace emitter
+        emitter = TraceEmitter(sink=sink, enabled=True)
+        set_default_emitter(emitter)
+        
+        # Set up context-level trace emitter
+        ctx_emitter = ContextTraceEmitter(sink=sink, enabled=True)
+        set_context_emitter(ctx_emitter)
+        
+    except ImportError:
+        # Gracefully degrade if Langfuse not installed
+        pass
+    except Exception:
+        # Silently fail to avoid breaking CLI if observability setup fails
+        pass
+
+
 class OutputFormat(str, Enum):
     """Output format options."""
     text = "text"
@@ -38,6 +64,7 @@ class GlobalState:
     quiet: bool = False
     verbose: bool = False
     screen_reader: bool = False
+    observe: Optional[str] = None
     output_controller: Optional[OutputController] = None
 
 
@@ -98,6 +125,13 @@ def main_callback(
         "--screen-reader",
         help="Screen reader friendly output (no spinners/panels)",
     ),
+    observe: Optional[str] = typer.Option(
+        None,
+        "--observe",
+        "-O",
+        help="Enable observability (langfuse, langsmith, etc.)",
+        envvar="PRAISONAI_OBSERVE",
+    ),
 ):
     """
     PraisonAI - AI Agents Framework CLI.
@@ -110,11 +144,16 @@ def main_callback(
     state.quiet = quiet
     state.verbose = verbose
     state.screen_reader = screen_reader
+    state.observe = observe
 
     # Handle --json alias
     if json_output:
         state.output_format = OutputFormat.json
 
+    # Set up observability if requested
+    if observe == "langfuse":
+        _setup_langfuse_observability()
+    
     # Determine output mode
     if state.quiet:
         mode = OutputMode.QUIET

src/praisonai/praisonai/flow/components/PraisonAI/praisonai_agent.py

@@ -405,6 +405,9 @@ def build_agent(self) -> Any:
     def build_response(self) -> Message:
         """Execute the agent and return the response as a Message."""
         agent = self.build_agent()
+        
+        # Wire up observability if configured
+        self._setup_observability()
 
         # Get input value
         input_value = self.input_value
@@ -434,3 +437,19 @@ def _get_llm(self) -> str:
             if converted:
                 return converted
         return self.llm
+    
+    def _setup_observability(self) -> None:
+        """Auto-configure observability from environment variables."""
+        import os
+        observe = os.environ.get("PRAISONAI_OBSERVE", "")
+        if observe == "langfuse":
+            try:
+                from praisonai.observability.langfuse import LangfuseSink
+                from praisonaiagents.trace.context_events import (
+                    ContextTraceEmitter, set_context_emitter
+                )
+                sink = LangfuseSink()
+                emitter = ContextTraceEmitter(sink=sink, enabled=True)
+                set_context_emitter(emitter)
+            except ImportError:
+                pass  # Langfuse not installed, gracefully degrade

src/praisonai/praisonai/flow/components/PraisonAI/praisonai_agents.py

@@ -307,6 +307,9 @@ def build_agents(self) -> Any:
     def build_response(self) -> Message:
         """Execute the multi-agent workflow and return the response."""
         agents_instance = self.build_agents()
+        
+        # Wire up observability if configured
+        self._setup_observability()
 
         # Get input value
         input_value = self.input_value
@@ -326,3 +329,19 @@ def build_response(self) -> Message:
     async def build_response_async(self) -> Message:
         """Execute the multi-agent workflow asynchronously."""
         return await asyncio.to_thread(self.build_response)
+    
+    def _setup_observability(self) -> None:
+        """Auto-configure observability from environment variables."""
+        import os
+        observe = os.environ.get("PRAISONAI_OBSERVE", "")
+        if observe == "langfuse":
+            try:
+                from praisonai.observability.langfuse import LangfuseSink
+                from praisonaiagents.trace.context_events import (
+                    ContextTraceEmitter, set_context_emitter
+                )
+                sink = LangfuseSink()
+                emitter = ContextTraceEmitter(sink=sink, enabled=True)
+                set_context_emitter(emitter)
+            except ImportError:
+                pass  # Langfuse not installed, gracefully degrade