Bento Documentation

A trajectory is one OTel span that stays open across a multi-step turn. Subsequent bento.track_ai and tool_span calls in the same task become children of it, so the whole flow shows up as one trace instead of N independent rows. This is an advanced feature. For most apps, an integration or tracking events is enough. Trajectories matter when one trace must span multiple LLM calls and tool calls within a single logical turn. When bento.instrument() is active, spans the Google ADK integration captures share the trajectory’s trace_id. One with bento.begin(...) block stitches manual and integration spans into one trace.

bento.begin()

The context-manager form auto-finishes on exit and records exceptions on the trajectory span.

import bentolabs_sdk.analytics as bento

with bento.begin(
    event="user_turn",
    user_id="u1",
    input="What's the weather in Paris?",
    model="claude-3-5-sonnet-20241022",
    provider="anthropic",
    convo_id="conv_abc",
) as interaction:
    with interaction.tool_span(name="web_search", input={"q": "Paris"}) as ts:
        results = run_search("Paris")
        ts.set_output(results)

    bento.track_ai(event="thought", input="Composing reply...")

    interaction.update(output="It's 18C and partly cloudy in Paris.")

The imperative form is available for code that can’t use with:

interaction = bento.begin(event="user_turn", user_id="u1", input="...")
# do work, optionally call interaction.update(...) mid-flight
interaction.finish(output="...")

Parenting and isolation

Trajectories detach from any outer OTel context, the same as a bare track_ai. So they’re root spans in their own trace even when called inside a customer’s existing FastAPI / Django / etc. instrumented stack. track_ai calls inside a begin()/finish() block parent to the trajectory.

Trajectories must be finished in reverse open order (LIFO). Finishing an outer trajectory while an inner one is still open raises RuntimeError. Use with bento.begin(...) as i: to guarantee correct nesting.

Decorators

Both decorators wrap function-shaped work, and both work on sync and async functions.

@bento.interaction

Wraps a function in bento.begin() / interaction.finish(). The function name becomes the event name; the return value becomes output.value. It does not auto-capture arguments, which are often non-trivial to serialize and frequently contain sensitive data. To record them, call interaction.update(input=...) from inside the function, or use @bento.tool, which does capture.

@bento.interaction
def handle_message(msg: str) -> str:
    return reply

@bento.interaction(event="user_turn", capture_output=False)
def handle_message(msg: str) -> str:
    ...

Option	Default	Effect
`event`	function name	Override the event name.
`capture_output`	`True`	Set the return value as `output.value`. JSON-serialized if not a string.

@bento.tool

Wraps a function in bento.tool_span(...). The function’s bound arguments become input.value (as a JSON dict), and the return value becomes output.value. The span carries openinference.span.kind="tool" so downstream classification picks it up. Set capture_input=False or capture_output=False for sensitive args or huge return payloads.

@bento.tool
def web_search(query: str, limit: int = 10) -> list[str]:
    return [...]

@bento.tool(name="search", capture_input=False)
def web_search(query: str) -> list[str]:
    ...

Option	Default	Effect
`name`	function name	Override the span name.
`capture_input`	`True`	Capture bound arguments as `input.value`. `self`/`cls` are dropped.
`capture_output`	`True`	Set the return value as `output.value`.

Tool spans

The module-level helper opens a tool span without threading an Interaction handle through code:

with bento.tool_span("web_search", input={"q": "..."}) as ts:
    result = run_search(...)
    ts.set_output(result)

Same parenting rule as track_ai: parents to the active trajectory if begin() is open in this task, else becomes a detached root. Exceptions raised inside the block are recorded on the span (status=ERROR, exception event) and re-raised.

ToolSpan API

A ToolSpan carries two methods:

Method	Purpose
`ts.set_output(value)`	Write to `output.value`. Strings pass through; dicts/lists are JSON-serialized.
`ts.set_attribute(key, value)`	Escape hatch for arbitrary OTel attributes.

Interaction API

An Interaction is the handle begin() returns:

Method	Purpose
`interaction.update(input=..., output=..., properties=...)`	Patch attributes on the open trajectory before finish.
`interaction.finish(output=..., properties=...)`	End the trajectory span. Idempotent.
`interaction.tool_span(name, input=..., properties=...)`	Open a child tool span under this trajectory.
`interaction.event_id`	The trajectory’s span ID (16-hex string).
`interaction.convo_id`	The conversation ID passed to `begin()`.

Get started

Integrations

Manual tracking

Advanced

Trajectories

bento.begin()

Parenting and isolation

Decorators

@bento.interaction

@bento.tool

Tool spans

ToolSpan API

Interaction API

​bento.begin()

​Parenting and isolation

​Decorators

​@bento.interaction

​@bento.tool

​Tool spans

​ToolSpan API

​Interaction API

bento.begin()

Parenting and isolation

Decorators

@bento.interaction

@bento.tool

Tool spans

ToolSpan API

Interaction API