Python SDK quickstart

Sovara records supported LLM, MCP, and explicitly traced tool calls inside an SDK run. Every Python integration starts with one project-bound SovaraClient.

Install

Follow Installation to use an existing Sovara environment or choose a local, remote, or headless setup. Then add the packages used by this example:

uv add sovara openai-agents

Set OPENAI_API_KEY in the environment before running the example.

A complete example

This example uses two child agents to compare the weather in Zurich and Boston. Their model and framework tool calls are recorded automatically; trace records the custom comparison step.

from agents import Agent, Runner, function_tool
from sovara import SovaraClient, trace  

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


@function_tool
def get_zurich_temperature() -> int:
    """Get the current temperature in Zurich in Celsius."""
    return 22


@function_tool
def get_boston_temperature() -> int:
    """Get the current temperature in Boston in Celsius."""
    return 27


zurich_agent = Agent(
    name="Zurich weather agent",
    instructions="Call the weather tool and return only the temperature.",
    model="gpt-5.4-mini",
    tools=[get_zurich_temperature],
    output_type=int,
)

boston_agent = Agent(
    name="Boston weather agent",
    instructions="Call the weather tool and return only the temperature.",
    model="gpt-5.4-mini",
    tools=[get_boston_temperature],
    output_type=int,
)


@trace(name="choose warmer city")  
def choose_warmer_city(zurich: int, boston: int) -> str:
    if zurich == boston:
        return f"Boston and Zurich are equally warm at {zurich} C."
    city = "Zurich" if zurich > boston else "Boston"
    return f"{city} is warmer ({boston} C in Boston, {zurich} C in Zurich)."


def main() -> None:
    question = "Which city is warmer, Boston or Zurich?"
    with sovara_client.run("compare city weather"):  
        # Attach the user-visible request to the top-level run.  #
        sovara_client.log_input(question)  

        # Each subrun groups one delegated agent's work into an expandable child run.  #
        with sovara_client.subrun("Zurich weather agent"):  
            zurich = Runner.run_sync(zurich_agent, question).final_output

        with sovara_client.subrun("Boston weather agent"):  
            boston = Runner.run_sync(boston_agent, question).final_output

        answer = choose_warmer_city(zurich, boston)
        # Attach the final user-visible result to the top-level run.  #
        sovara_client.log_output(answer)  

    print(answer)


if __name__ == "__main__":
    main()

Sovara records supported framework tools such as @function_tool and MCP calls automatically. Do not add @trace to those tools as well; reserve it for important operations that are not already captured.

Subruns are optional, but provide a useful abstraction for grouping child agents or delegated phases into expandable units.

Verify one run

Save the example as weather_agent.py, then run it normally:

uv run python weather_agent.py

Open the weather-agent project in Sovara to inspect the run. A run typically corresponds to one chat session or one workflow execution. log_input() and log_output() populate the Input and Output columns in the Runs table, so you can scan results without opening each run:

Sovara Runs table showing the logged weather comparison input and output

Open the run to see both weather-agent subruns, their LLM and tool calls, and the final Choose Warmer City step:

Sovara trace showing Zurich and Boston weather-agent subruns and the final city comparison

Next steps

Use the SDK for subruns, persistent run IDs, lessons, and metadata.
API reference for the exact public surface.
Troubleshooting for missing runs or steps.

Get started

Use the SDK

Reference

Python SDK quickstart

Install

A complete example

Verify one run

Next steps

​Install

​A complete example

​Verify one run

​Next steps

Install

A complete example

Verify one run

Next steps