Use the SDK

The ownership model

The Python SDK exposes two top-level building blocks:

SovaraClient owns project identity and trace-scoped helpers.
trace wraps application functions that should appear as steps.

from sovara import SovaraClient, trace

sovara_client = SovaraClient(project_name="support-agent")

All trace, subtrace, logging, lesson, and control operations go through that client. The project is not inferred from the working directory.

Top-level traces

Use a top-level trace for a workflow, evaluation sample, batch job, or durable conversation. A recording session opens that trace for appending work; a turn groups one interaction within it.

with sovara_client.trace("research-and-answer"):
    answer = run_agent()

The SDK registers the trace with the exec server when the context opens and finalizes it when the context exits. The same context works with with and async with. For a durable conversation or workflow, pass your own stable identifier as trace_id, or reuse the trace ID yielded by a previous SDK trace. Reuse either value to add new steps to the same trace in that project.

with sovara_client.trace("support chat", trace_id=chat_id) as trace_id:
    reply = agent.reply(message)
    if trace_id is not None:
        sovara_client.log(trace_id=trace_id, trace_input=message, trace_output=reply)

Keep prompts, messages, and secrets out of trace_id; use a stable ID such as a chat, ticket, or job ID. The context yields the trace ID. Omit trace_id to create a new trace. Pass that ID to the CLI, here as TRACE_ID:

sovara probe "$TRACE_ID"

Steps and explicit tracing

Inside a trace, supported provider and MCP calls become ordered steps with input, output, latency, status, and error data. trace adds the same visibility to important application work that automatic instrumentation does not capture.

@trace
def lookup_customer(customer_id: str) -> dict:
    return crm.lookup(customer_id)

Place explicit tracing at shared tool or dispatch chokepoints. A trace filled with miscellaneous helper calls is harder to understand than one that exposes the agent’s decisions and meaningful actions.

Subtraces

Subtraces organize child agents, delegated branches, parallel work, and coherent multi-step phases under the active trace.

with sovara_client.trace("finance-eval"):
    with sovara_client.subtrace("sample-42"):
        trace_one_sample("sample-42")

Use subtrace() for child work. Nesting trace() does not create a child trace.

Trace metadata

Use log() to attach input, output, and custom fields to a trace.

with sovara_client.trace("answer-question") as trace_id:
    answer = agent(question)
    if trace_id is not None:
        sovara_client.log(trace_id=trace_id, trace_input=question, trace_output=answer,
                          answered=True, latency_budget_ms=2500)

Input and output must be strings; serialize structured values with json.dumps(). Custom fields accept booleans, integers, finite floats, or strings. Omit absent values instead of passing None. If recording is unavailable, trace_id is None; skip logging for that trace. See the API reference for details. To group sample traces and record verdicts, follow the Evaluations guide.

Lessons

When automatic injection is enabled and the required models are configured, supported model calls retrieve from the project’s production lessons. Unapplied proposals are not used. Narrow retrieval with lesson_scope on a trace or subtrace:

with sovara_client.trace("answer-question", lesson_scope="financebench/"):
    answer = call_model(question)

Temporarily replace the active scope inside a smaller block:

with sovara_client.lesson_scope(["conventions/", "markets/"]):
    answer = call_model(question)

See runtime retrieval for project settings.

Controls and concurrency

with sovara_client.disable_tracing():
    warm_cache_without_recording()

with sovara_client.disable_lesson_injection():
    answer_without_lessons()

Async tasks inherit context. Create the with_context(...) wrapper inside the active trace before submitting it to a thread pool:

from concurrent.futures import ThreadPoolExecutor

with sovara_client.trace("parallel-research", capture_logs=False):
    with ThreadPoolExecutor() as pool:
        result = pool.submit(sovara_client.with_context(research), question).result()

Await tasks and consume provider streams before leaving the recording context. For concurrent top-level traces, set capture_logs=False to avoid mixing process stdout/stderr between traces.

Run the application

Run the application normally. The SDK records the trace:

uv run python agent.py

Open Sovara to inspect the recorded trace. Use the API reference for exact signatures.

Explicit conversation turns

trace() opens a recording session; it does not create an implicit turn. Declare interactions with scoped turn() blocks. Setup, cleanup, and other work outside those blocks are still captured, with no turn membership.

with sovara_client.trace("conversation", trace_id="chat-123"):
    setup()
    with sovara_client.turn(turn_input="Hi."):
        respond()
    with sovara_client.turn(turn_input="Another question."):
        respond()
    cleanup()

For one recording per interaction, reuse the same trace_id and declare the interaction explicitly:

for message in messages:
    with sovara_client.trace("conversation", trace_id="chat-123"):
        with sovara_client.turn(turn_input=message):
            respond()

Both trace() and turn() support async with. turn_input is an optional string for the interaction; logged input and output describe the whole trace. Do not nest turns in the same trace. Await tasks and consume streams before leaving the recording context.

Get started

Reference

Use the SDK

The ownership model

Top-level traces

Steps and explicit tracing

Subtraces

Trace metadata

Lessons

Controls and concurrency

Run the application

Explicit conversation turns

​The ownership model

​Top-level traces

​Steps and explicit tracing

​Subtraces

​Trace metadata

​Lessons

​Controls and concurrency

​Run the application

​Explicit conversation turns

The ownership model

Top-level traces

Steps and explicit tracing

Subtraces

Trace metadata

Lessons

Controls and concurrency

Run the application

Explicit conversation turns