> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace your agent

> Add structure and details to your logs.

This guide shows how to instrument an existing agent so Sovara records its model
calls, tool calls, runtime metadata, and more.

To track runs with Sovara, instrument your code with the SDK. Sovara's
high-level run context lets you trace your entire agent with one line of code
(see [Quickstart](/get-started/quickstart)). Inside that context, Sovara records
supported LLM and tool calls and makes them available for analysis and
optimization. You can add more instrumentation to structure the trace and make
it easier to understand.

A typical workflow to implement this instrumentalization is this:

1. **Let a coding agent instrumentalize your code:** Use the turnkey setup
   below to launch Codex or Claude Code with the Sovara skill and instrument
   your codebase.
2. **Fine-tune the instrumentation if needed:** For more fine-grained control,
   see [Instrument Manually with the Tracing SDK](#instrument-manually-with-the-tracing-sdk).

## Instrument via coding agents and the Sovara CLI

Coding agents can give you a good starting point for inserting logging statements.
The Sovara CLI allows you to launch Claude Code or Codex with set up instructions
to instrumentalize your code.

Install the CLI if you haven't already:

<Tabs>
  <Tab title="macOS, Linux, WSL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    irm https://apps.sovara-labs.com/cli/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://apps.sovara-labs.com/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
    ```
  </Tab>
</Tabs>

Run `sovara status`. If it succeeds, keep using the configured environment. If
it fails, follow [Installation](/get-started/installation) to choose a local,
remote, or headless setup. Then go to the project folder containing the code
you want to instrumentalize.

### Turnkey instrumentalization

If you want to run one command and have the coding agent instrument the code on
its own, run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara setup
```

Sovara launches Codex or Claude Code automatically. If both are installed, it
asks you which one to use.

### Manually steering the coding agent

Alternatively, if you want to steer the coding agent manually, do the following:

1. Refresh the assistant skill:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara install-skill --target both
```

2. Get started by asking Claude Code or Codex something like this:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use the Sovara skill to set up this project. Follow its Repository Setup section
from start to finish, make the required dependency and instrumentation changes,
record one representative run, and show me how to inspect it. Ask before any
verification that would make a paid provider call.
```

For more CLI details, see [Claude Code](/cli/claude-code),
[Codex](/cli/codex), and the [CLI overview](/cli/overview).

## Instrument manually with the SDK

To make the code changes yourself, follow the SDK documentation for your
language:

* [Python SDK](/sdks/python/quickstart)
* [TypeScript SDK](/sdks/typescript/quickstart)