The adoption ladder
Three ways to get agents into Trefur. Each rung is worth climbing on its own — you never have to reach the top to get value, and you never have to start at the bottom.
| Rung | What you write | What you get |
|---|---|---|
| 1. Connectors | nothing | Agents discovered from your provider account, with the credential and the human who owns it |
| 2. Collector | one environment variable | Everything in rung 1, plus runs, steps, tool calls and cost from processes you run yourself |
| 3. SDK | one init(), then a name per call | Everything above, plus per-call agent identity, sub-agent lineage, and the richest trust signal |
“We have a thousand agents — that's a thousand integrations”
It isn't, and this is the most common reason teams stall before starting.
agent_name is a per-call parameter, not an install-time constant. One init() in one service can emit a thousand distinct agent identities, because you pass the name at the point you do the work:
trefur.observe(agent_name="invoice-reconciler", ...)
trefur.observe(agent_name="contract-summariser", ...)That holds in every SDK we publish — Python, JavaScript/TypeScript, Go, Rust, Java and .NET all take the name per call.
So the integration work is linear in deploy units, not in agents. Ten services running a thousand logical agents is ten integrations, not a thousand. A single service that dispatches to a hundred agent types is one.
Rung 1 — Connectors (zero code)
Connect a provider account and Trefur discovers the agents already running in it. No deploy, no library, no change to anything you ship.
This is the only rung that yields both the credential an agent used and the human who owns that credential, because the provider knows both and tells us. The cost is constant no matter how many agents you have.
Start here if you want to see your estate before deciding what to instrument. See Integrations for the provider list.
Rung 2 — Collector (one environment variable)
Run the collector alongside your workload and point it at Trefur. You declare one agent name for the process; everything that process does is attributed to it.
You get real execution data — runs, steps, tool calls, tokens, cost — without touching application code. Right rung when you control the deployment but do not want to modify the program, or when the program is not in a language we ship an SDK for. See Collector quickstart and When to use the collector.
Rung 3 — SDK (one init, a name per call)
Import the SDK, initialise once, and pass agent_name on each call.
This is the only rung that distinguishes agents within a process, and the only one that captures sub-agent lineage — when one agent spawns another, the child's work is recorded as part of the parent's run rather than as an orphan (see Multi-agent traces).
Worth it when several logical agents share a process, or when you want the trust signal to reflect what each agent actually did rather than what the process did in aggregate. Start at Quickstart.
Mixing rungs
They compose. Connectors for the estate you have not instrumented, the collector for services you run but do not want to change, the SDK where identity precision matters. Most teams end up on more than one rung and that is the expected shape, not a migration half-finished.