agentix.tracing

tracing

OpenTelemetry tracing.

Turn an agent run into a span tree so you can see latency, tokens, cost, and tool/guard activity in your existing observability stack. Three pieces, all opt-in and composable:

• :class:TracingModel — wrap a model; each call becomes a agentix.model span with token/cost attributes.
• :func:tracing_events — an :class:~agentix.events.AgentEvents that opens a agentix.tool.<name> span per tool call (with guard/confirm sub-events).
• :func:trace_run — an async context manager for the root agentix.run span, under which the model/tool spans nest.

Usage::

agent = Agent(model=TracingModel(my_model), system_prompt="...",
              tools=[...], events=tracing_events())
async with trace_run():
    outcome = await agent.run("...")

Requires opentelemetry-api (pip install "agentix[otel]"); you configure the TracerProvider/exporter in your app. The opentelemetry import is deferred, so importing agentix never requires it.

TracingModel

TracingModel(model: ModelFn, *, tracer: Any = None)

Wrap a model so each call is recorded as a span with token/cost attrs.

tracing_events

tracing_events(*, tracer: Any = None) -> AgentEvents

An AgentEvents that spans each tool call (with guard/confirm events).

Tool spans nest under whatever span is current (e.g. the :func:trace_run root). Create a fresh instance per agent.

trace_run async

trace_run(
    name: str = "agentix.run", *, tracer: Any = None
) -> AsyncIterator[Any]

Open the root span for a run; yields the span so you can add attributes.

instrument

instrument(agent: Agent, *, tracer: Any = None) -> Agent

Wire tracing into an existing agent in one call: wrap its model in :class:TracingModel and merge :func:tracing_events into its events (any callbacks you already set are preserved and run alongside). Mutates and returns the agent. Still wrap the run in :func:trace_run for a root span.

agent = instrument(Agent(model=m, system_prompt="...", tools=[...]))
async with trace_run():
    await agent.run("...")