Skip to content

Langfuse Observability

weego edited this page Nov 15, 2026 · 2 revisions

Langfuse Observability

LightAgent has internal structured traces through trace=True. It also exposes tracetools configuration for Langfuse-style observability.

Langfuse is optional in v1.0.0. Use python -m pip install 'lightagent[langfuse] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0' when you need the SDK. See trace and evaluation for the SDK-free path.

Internal Trace First

Start with built-in trace events:

result = agent.run("hello", result_format="object", trace=True)
print(result.trace)

Use Langfuse when you need an external trace UI, team collaboration, or long-term observability.

Langfuse Configuration

tracetools = {
    "TraceTool": "langfuse",
    "TraceToolConfig": {
        "langfuse_enabled": True,
        "langfuse_host": "https://cloud.langfuse.com",
        "langfuse_public_key": "your_public_key",
        "langfuse_secret_key": "your_secret_key",
    },
}

agent = LightAgent(
    name="Agent A",
    instructions="You are a helpful agent.",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    debug=True,
    log_level="DEBUG",
    tracetools=tracetools,
)

Security Notes

  • Do not commit Langfuse keys.
  • Prefer environment variables for keys.
  • Review what prompts, tool arguments, tool outputs, and metadata are sent to external observability systems.
  • Disable external tracing for sensitive workloads unless your compliance process allows it.

Built-in Trace vs Langfuse

Need Use
Local debugging trace=True and agent.export_trace()
Production timeline view Langfuse
Sharing issue reports Redacted trace=True output
Long-term cost and latency analytics Langfuse

Clone this wiki locally