Quickstart

Pick a language, install the SDK, and you're tracing in three lines. Everything that follows is optional polish.

1. Get an API key

Sign in to app.trefur.com (a workspace is created for you). Go to Settings → Platform → API keys and mint an Observe ingest key — it starts with trf_obs_. Copy it now; the full key is shown only once.

2. Install + initialise

JavaScript / TypeScript

npm install @trefur/observe

import OpenAI from 'openai';
import { TrefurObserve, patchOpenAI } from '@trefur/observe';

TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: process.env.TREFUR_AGENT_NAME ?? 'my-agent' },
});

const openai = new OpenAI();
patchOpenAI(OpenAI, TrefurObserve.getInstance());

Python

pip install trefur-observe

import os
from anthropic import Anthropic
from trefur_observe import TrefurObserve, patch_anthropic

TrefurObserve.init(
    api_key=os.environ["TREFUR_API_KEY"],
    agent={"name": os.environ.get("TREFUR_AGENT_NAME", "my-agent")},
)

client = Anthropic()
patch_anthropic(TrefurObserve.get_instance())

Go

go get github.com/trefur-ai/trefur-sdks/go/observe-go

import (
    "os"

    observe "github.com/trefur-ai/trefur-sdks/go/observe-go"
)

func main() {
    client := observe.Init(observe.Config{
        APIKey:    os.Getenv("TREFUR_API_KEY"),
        AgentName: os.Getenv("TREFUR_AGENT_NAME"),
    })
    defer client.Shutdown()
    // ... your agent runs here
}

Rust

cargo add trefur-observe

use trefur_observe::{Client, AgentRun, AgentStep};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder()
        .api_key(std::env::var("TREFUR_API_KEY")?)
        .build()?;
    let mut run = AgentRun::new("custom", "my-agent", "completed");
    run.steps.push(AgentStep::tool_use("search"));
    client.record(run).await;
    client.flush().await?;
    Ok(())
}

Java

implementation 'ai.trefur:trefur-observe:0.5.0'

import ai.trefur.observe.client.TrefurObserveClient;
import ai.trefur.observe.model.AgentRun;
import ai.trefur.observe.model.AgentStep;
import java.time.Instant;

try (TrefurObserveClient client = TrefurObserveClient.builder()
        .apiKey(System.getenv("TREFUR_API_KEY"))   // trf_obs_*
        .build()) {
    AgentRun run = new AgentRun(
            "langchain4j", "my-agent", "completed", Instant.now().toString());
    AgentStep step = new AgentStep(
            "tool_call", Instant.now().toString(), "completed");
    step.setToolName("search");
    run.getSteps().add(step);
    client.record(run);
    client.flush();
}

.NET

dotnet add package Trefur.Observe

using Trefur.Observe.Client;
using Trefur.Observe.Model;

using var client = TrefurObserveClient.Configure()
    .ApiKey(Environment.GetEnvironmentVariable("TREFUR_API_KEY")!)   // trf_obs_*
    .Build();

var run = new AgentRun
{
    Framework = "semantic-kernel",
    AgentName = "my-agent",
    Status    = "completed",
    StartedAt = DateTime.UtcNow.ToString("o"),
};
run.Steps.Add(new AgentStep
{
    StepType  = "tool_call",
    ToolName  = "search",
    StartedAt = DateTime.UtcNow.ToString("o"),
    Status    = "completed",
});
client.Record(run);
await client.FlushAsync();

3. Run your agent

That's it. Every Anthropic / OpenAI / LangChain / CrewAI call your agent makes — including streaming responses, tool calls, sub-agent spawns — is captured. Visit app.trefur.com to see the trace.

4. (Optional) Wire production observability

TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  onError: (err, ctx) => {
    // ctx.kind is 'send' | 'flush_policy' | 'flush_transactions'
    myLogger.warn('trefur ingest failed', { kind: ctx.kind, msg: err.message });
  },
});

Without an onError callback the SDK retries silently and prints a single console.warn on first failure. Wire it to your error tracker in production.

What's next?

• How telemetry reaches Trefur — the full ingest-layer matrix (SDK vs collector vs OAuth discovery vs webhook vs OTel forwarding).
• SDK reference — full option table, every adapter, every step-type.
• Collector reference — if you have a CLI, OS-level shell hook, MCP proxy, or LLM HTTP proxy traffic to capture.
• Integrations — connect Google Workspace, Microsoft 365, OpenAI Admin API, Anthropic Admin API, Slack, Atlassian, etc., via OAuth.