Skip to main content
This guide records a real FinanceBench agent run in Sovara. It starts from the demo repository so you can verify the full flow before instrumenting your own agent.

​
1. Install Git LFS

The demo repository uses Git LFS for the FinanceBench PDFs and PageIndex data. Install and enable Git LFS before cloning the repository. 
brew install git-lfs
git lfs install

​
2. Clone the Demo

Clone the demo to ~/sovara-demo. The fixed path keeps the docs, desktop app, and support instructions aligned. 
git clone https://github.com/SovaraLabs/sovara-demo-py ~/sovara-demo
cd ~/sovara-demo

​
3. Install uv

The demo uses uv to create the Python environment and install dependencies. 
curl -LsSf https://astral.sh/uv/install.sh | sh
If your terminal still says uv: command not found, close and reopen the terminal, then run: 
uv --version

​
4. Open Sovara

Install the Sovara desktop app from Installation, then open it and keep it running while you run the demo. The bundled desktop app starts the local Sovara server while the app is open. If Sovara is not open, the demo cannot record a trace.

​
5. Configure Demo API Keys

The demo agent reads its provider keys from ~/sovara-demo/.env. 
cp .env.example .env
Open .env and set the keys used by the demo agent: 
OPENAI_API_KEY=<your OpenAI API key>
ANTHROPIC_API_KEY=<your Anthropic API key>

​
6. Configure Sovara Model Endpoints

Sovara also needs its own model endpoints for trace chat, summaries, annotation support, embeddings, and other analysis. These settings are separate from the demo agent’s .env file. In the desktop app, open Settings. For each required endpoint, choose one of the predefined providers and models, add the credential, and click Save. Use a custom or locally hosted endpoint only if your setup requires it.

​
7. Run the First Trace

From ~/sovara-demo, run sample 81 and queue the run for annotation: 
uv run main.py --sample-id 81 --queue-for-annotation
The first run can take a few minutes because uv may need to create the Python environment and install dependencies. When the command completes, it prints a JSON result in the terminal and records the run in Sovara.

​
8. Inspect the Run

Go back to the desktop app and open the sovara-demo project.
  1. Open Runs.
  2. Select the newest run.
  3. Click Open Run.
The run view should show the recorded inputs, outputs, model calls, tool calls, logs, and runtime metadata. Because the command used --queue-for-annotation, the run should also appear in the annotation queue. Open the annotation view, then click Inspect run to inspect the trace from the review workflow.

​
9. Run More Samples

Run a few more sample IDs so there are multiple traces to compare and review: 
uv run main.py --sample-id 82 --queue-for-annotation
uv run main.py --sample-id 83 --queue-for-annotation
uv run main.py --sample-id 84 --queue-for-annotation
Each command records a new run and adds it to the annotation queue.

​
Apply This to Your Own Agent

The demo records a trace by activating Sovara around the code path that performs agent work. Use the same pattern in your own Python or TypeScript agent.

​
Python

Add sovara.run(...) around the part of your code that should become a run in Sovara. 
 from openai import OpenAI
+import sovara

 client = OpenAI()

 def answer_question(question: str) -> str:
+    with sovara.run("answer-question"):
+        sovara.log_input(question)
         # your existing retrieval, tool calls, and model calls stay here
         response = client.responses.create(
             model="gpt-5.4-mini",
             input=question,
         )
+        sovara.log_output(response.output_text)
         return response.output_text
sovara.run("name") creates a run context for the current folder. sovara.log_input(...) and sovara.log_output(...) attach the user-visible input and final output. sovara.queue_for_annotation() sends the active run to the annotation review workflow.

​
TypeScript

In TypeScript, wrap the async entrypoint with withSovaraRun(...). 
 import OpenAI from "openai";
+import { withSovaraRun } from "@sovara/runner";

 const client = new OpenAI();

 async function answerQuestion(question: string): Promise<string> {
+  return withSovaraRun("answer-question", async () => {
     const response = await client.responses.create({
       model: "gpt-5.4-mini",
       input: question,
     });
     return response.output_text;
+  });
 }
withSovaraRun("name", fn) creates a run context for fn and records supported model calls made inside it.