SDK Reference · Agent instrumentation
Instrument with a coding agent
You do not have to wire tracing by hand. Bear Lumen ships an instrumentation Skill: a set of instructions your coding agent follows to add cost tracing across a whole codebase, wrapping provider clients, placing spans around your units of work, declaring outcomes, and setting budgets. This page explains what the Skill does and how to point your agent at it. For the human reference on each concept, see Tracing agentic work.
Requires node-sdk 0.12.0 or python-sdk 0.10.0a1
The tracing surface the Skill instruments ships in @bearlumen/node-sdk 0.12.0 and bearlumen 0.10.0a1 and later. Run npm install @bearlumen/node-sdk@latest or pip install -U bearlumen before your agent starts.
What the Skill adds: a five-rung ladder
The Skill follows an adoption ladder in order and stops at the rung you asked for. Each rung is independently valuable, so partial adoption is a supported state, not a degraded one. This is the summary; every concept is documented in full on Tracing agentic work.
| Rung | You add | You get |
|---|---|---|
| 1 | wrap() your provider clients | Every AI call costed automatically: provider, model, tokens, cost. |
| 2 | A session id at each request or conversation boundary | Cost per run or per conversation, summed across every call inside it. |
| 3 | Spans around your units of work, with an outcome on the span that produces the value | The agent call tree, cost per branch, and cost per outcome (the COGS number). |
| 4 | traceContext() on queue messages, a unitKey on retryable consumers | Trees that survive process boundaries, with honest retry accounting. |
| 5 | A budget fuse on any span that can run away | A client-side cost cap that stops a runaway before it spends, not tomorrow. |
How to use it
The Skill is a single Markdown file (sdks/tracing-skill/SKILL.md) that ships bundled with both the @bearlumen/node-sdk and bearlumen packages, so once the SDK is installed the instructions are already in your dependency tree. Point your coding agent at it and let it work through the ladder against your codebase: it detects your language and SDK, finds every provider client and unit-of-work boundary, and applies the changes. The same Skill covers both Node.js and Python, so a mixed codebase is one instruction, not two.
Tell the agent where to stop. Ask for rung 1 to get every call costed with a one-line wrap(), or ask for the full ladder to get the call tree, outcomes, and budgets. When it finishes, it reports which clients it wrapped, where it placed spans, which outcomes and budgets it declared, and the taxonomy it standardized on.
What the agent verifies
The Skill does not stop at writing code. After a test run it flushes events and reads back what it wrote, so the instrumentation is proven rather than assumed:
attribution.sessionsshows the run with a plausible total, andattribution.sessionTreeshows the expected tree shape with a near-zerountracedbucket. A large untraced bucket means calls are escaping the spans, so the agent hunts down the unwrapped client or the missing span.costs.byOutcomeshows the declared outcomes with completed counts that match the number of test runs.- Shutdown is wired: short-lived processes call
shutdown()before exit so the last batch of events is never dropped.
Next steps
Tracing agentic work
The human reference for every concept the Skill applies: wrap(), spans, outcomes, budgets, and cross-process carriers, in Node.js and Python.
Cost attribution
How tagged spans and outcomes turn into cost per feature, per customer, and per unit of value once your codebase is instrumented.