Observability

Top-level taimoe.platform.init configures observability automatically. Use native traces and spans to describe Agent, model, and tool work:

from taimoe.platform import trace

with trace(
    "support-conversation",
    session_id="session-123",
    agent_id="support",
    team_id="customer-success",
) as run:
    with run.span("lookup-order", span_type="tool") as span:
        span.set_input({"order_id": "A-123"})
        result = lookup_order("A-123")
        span.set_output(result)

    with run.span("draft-answer", span_type="model") as span:
        answer = generate_answer(result)
        span.set_usage(prompt_tokens=120, completion_tokens=45, cost_usd=0.001)
        span.set_output(answer)

The outer trace exports its completed span batch when the context exits. Nested spans preserve parent_span_id. Exceptions mark the active span as an error and are re-raised.

Decorators

track_agent creates an Agent trace when none is active. track_action adds a child span to the current trace. Both support synchronous and async functions.

from taimoe.platform import track_action, track_agent

@track_agent("support")
async def run_support(message: str) -> str:
    return await retrieve_and_answer(message)

@track_action("retrieve")
async def retrieve_and_answer(message: str) -> str:
    ...

Export behavior

By default, telemetry export failure is non-fatal so observability does not break Agent execution. Configure observability directly with raise_on_export_error=True only when a test or controlled environment must fail closed.

Install taimoe-platform[otel] to mirror native Taimoe spans into the active OpenTelemetry provider. W3C-compatible trace and span IDs allow the same execution to correlate with downstream APM systems.

Avoid placing secrets or unfiltered personal data in span input, output, or attributes. The SDK serializes and truncates values, but data classification remains the caller’s responsibility.