Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bentolabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Most apps should set identity once at bento.init(...) — see Configuration → Identity getters. The helpers on this page cover the rare cases where init-time getters aren’t enough.
The cleanest place to set user_id, session_id, and tags is the getter callables on bento.init() — they fire on every span, including ones captured by an integration. The helpers on this page exist for the cases where init-time getters aren’t a good fit:
  • Identity becomes known mid-flow (e.g. after authentication inside an open trajectory).
  • A worker received identity over a queue and you want to scope it to one handler invocation.
  • You want to patch arbitrary attributes onto the currently-active span without restructuring the call site.

​
update_current_trace

Patch the OPEN trajectory’s root span. Use this when identity is known mid-flow and you want it reflected at the trace level (traces.user_id, traces.session_id, traces.tags). 
import bentolabs_sdk as bento

with bento.begin(event="user_turn") as interaction:
    user_id, session_id = await authenticate(request)
    bento.update_current_trace(user_id=user_id, session_id=session_id)
    # rest of the work
Keys are SDK-defined (gen_ai.user.id, gen_ai.conversation.id, langfuse.tags); you supply values.
​
user_id
str
Sets gen_ai.user.id on the trajectory root.
​
session_id
str
Sets gen_ai.conversation.id on the trajectory root.
​
tags
list[str]
Sets langfuse.tags on the trajectory root.
​
properties
dict
Arbitrary custom dimensions, written through _coerce_property_value so types are preserved.
No-op when no bento.begin(...) is open in the current task. If you’re emitting bare track_ai calls, pass the values directly to track_ai instead.

​
update_current_span

Set attributes on the currently active OTel span — the innermost open span, which may or may not be the trajectory root. 
with bento.tool_span("web_search") as ts:
    results = run_search(query)
    bento.update_current_span(properties={"result_count": len(results), "cache_hit": False})
Use this when you want a property pinned to the inner span and don’t have a direct handle to it (deep helper functions, callbacks invoked by an integration).
​
properties
dict
Keys/values written to the currently active span. Same type-fidelity rules as track_ai(properties=...) — see Properties.
update_current_span reads OTel’s current context, so it sees integration-captured spans too. Calling it inside a callback that ADK invokes will write the property onto that span.

​
propagate_attributes

Scoped identity override for the current task. Per-task overrides take precedence over the global getters registered at init(). 
with bento.propagate_attributes(user_id="u_42", session_id="conv_99"):
    await agent.run(query)        # every span tagged automatically
Use this when the framework-state pattern doesn’t apply — e.g. inside a worker that received identity over a message queue and wants to scope it to one handler invocation.

​
Three-value kwargs

Each kwarg accepts three distinct values:
PassEffect
(omitted)Inherit from any outer propagate_attributes scope or the global source.
A value (e.g. user_id="u_42")Use this value for the scope.
Explicit NoneClear the field for the scope, shadowing any outer override and skipping the global source.
Restores the prior values on exit. Identity sources registered at init() resume after the block.

​
How they compose

The SDK resolves identity in this order, highest priority first:
  1. Explicit kwarg on the call — bento.track_ai(user_id="x", ...) or bento.begin(user_id="x", ...) always wins.
  2. update_current_trace(...) patches set on the trajectory root.
  3. propagate_attributes(...) scope active in the current task.
  4. Init-time getters — bento.init(user_id=lambda: ...) resolved per span.
The first source that returns a non-None value at span-emit time is the one that lands in the dashboard.

​
See also

Integrations

Identity getters at init() — the zero-code path.

Trajectories

Open a begin() block to host update_current_trace patches.