Langfuse exporter

Koog provides built-in support for exporting agent traces to Langfuse, a platform for observability and analytics of AI applications.
With Langfuse integration, you can visualize, analyze, and debug how your Koog agents interact with LLMs, APIs, and other components.

For background on Koog’s OpenTelemetry support, see the OpenTelemetry support.

---

Setup instructions

1. Create a Langfuse project. Follow the setup guide at Create new project in Langfuse
2. Obtain API credentials. Retrieve your Langfuse public key and secret key as described in Where are Langfuse API keys?
3. Pass the Langfuse host, private key, and secret key to the Langfuse exporter. This can be done by providing them as parameters to the addLangfuseExporter() function, or by setting environment variables as shown below:

   export LANGFUSE_HOST="https://cloud.langfuse.com"
   export LANGFUSE_PUBLIC_KEY="<your-public-key>"
   export LANGFUSE_SECRET_KEY="<your-secret-key>"

Configuration

To enable Langfuse export, install the OpenTelemetry feature and add the LangfuseExporter.
The exporter uses OtlpHttpSpanExporter under the hood to send traces to Langfuse’s OpenTelemetry endpoint.

Example: agent with Langfuse tracing

fun main() = runBlocking {
    val apiKey = "api-key"

    val agent = AIAgent(
        executor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.CostOptimized.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addLangfuseExporter()
        }
    }

    println("Running agent with Langfuse tracing")

    val result = agent.run("Tell me a joke about programming")

    println("Result: $result\nSee traces on the Langfuse instance")
}

What gets traced

When enabled, the Langfuse exporter captures the same spans as Koog’s general OpenTelemetry integration, including:

• Agent lifecycle events: agent start, stop, errors
• LLM interactions: prompts, responses, token usage, latency
• Tool calls: execution traces for tool invocations
• System context: metadata such as model name, environment, Koog version

Koog also captures span attributes required by Langfuse to show Agent Graphs.

When visualized in Langfuse, the trace appears as follows:

For more details on Langfuse OpenTelemetry tracing, see:
Langfuse OpenTelemetry Docs.

---

Troubleshooting

No traces appear in Langfuse

• Double-check that LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, and LANGFUSE_SECRET_KEY are set in your environment.
• If running on self-hosted Langfuse, confirm that the LANGFUSE_HOST is reachable from your application environment.
• Verify that the public/secret key pair belongs to the correct project.