> ## 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.

# Migrate to the current SDKs

> Upgrade an application from an earlier Sovara Python or TypeScript SDK release.

The current SDKs use runner-api 6 and record model calls only after `auto_instrument()` /
`autoInstrument()`.

## Before you start

Update the exec server first. The current SDKs raise `CompatibilityError` against an older
one.

## Upgrade with a coding agent

Paste this prompt into a coding agent at the root of your repository:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Upgrade this repository's Sovara SDK integration to the current SDK. Change only what
the upgrade needs.

1. Upgrade every use of the `sovara` Python package and the `@sovara/sdk` npm package to
   the latest release.

2. Turn on automatic recording once at startup, before creating any provider client,
   agent or MCP client:
   - Python: `sovara.auto_instrument()`.
   - TypeScript: `await autoInstrument()`, also before any code keeps a reference to
     `fetch`. Outside an ES module, await it at the start of the entry function.

3. Rename deprecated APIs:
   - `run` -> `trace`, `subrun` -> `subtrace`, `get_run_id` / `getRunId` ->
     `get_trace_id` / `getTraceId`, `run_id` -> `trace_id` (`runId` -> `traceId`).
   - In `log()`: `run_input` / `run_output` -> `trace_input` / `trace_output`.
   - TypeScript `logInput`, `logOutput` and `logMetrics` are removed. Inside the trace,
     read `const traceId = client.getTraceId()`; if set, call
     `await client.log({ traceId, traceInput, traceOutput, fields })`. Input and output
     are strings (use `JSON.stringify`); metrics go in `fields`.

4. Import only from `sovara` and `@sovara/sdk`, plus the integration packages below.

5. Errors:
   - Server failures raise `RecordingError` from `log`, `create_eval_run` /
     `createEvalRun`, `turn()`, explicit steps, cross-process functions and completing a
     trace. Catch it where the agent must keep running.
   - Invalid use raises `SovaraConfigError`.
   - Replace handling of the old `RuntimeError`, `ValueError`, `TypeError` or
     `ValidationError` from Sovara with these.

6. Remove `@trace` / `trace()` from generator functions; record them with
   `start_step()` / `startStep()` instead.

7. Framework integrations are separate packages:
   - LangChain / LangGraph: install `sovara-langchain` / `@sovara/langchain`. Add
     `SovaraMiddleware()` / `sovaraMiddleware()` last in `create_agent` / `createAgent`
     middleware, or wrap other chat models with `wrap_chat_model` / `wrapChatModel`. Use one
     per model.
   - OpenAI Agents SDK: install `sovara-openai-agents` / `@sovara/openai-agents` and call
     `sovara_openai_agents.instrument()` / `await instrumentOpenAIAgents()` at startup, or
     tool calls are no longer recorded.

8. Server URL: `SOVARA_SERVER_URL` now sets the server the SDK records to, and
   `SOVARA_EXEC_SERVER_URL` is its older name. Older Sovara versions used
   `SOVARA_SERVER_URL` for the app-server URL (`http://127.0.0.1:5959` locally). Remove any
   such setting from shell profiles and deployment configuration, then sign in with
   `sovara login --url <url>`, or set `SOVARA_SERVER_URL` to the server that records.

9. Run the agent once and check that its trace shows model calls as steps
   (`sovara probe <trace-id>`). Report what you changed and the trace ID.
```

## After upgrading

If a trace has no model or tool steps, `auto_instrument()` / `autoInstrument()` runs too
late or not at all. See troubleshooting for [Python](https://docs.sovara-labs.com/sdks/python/troubleshooting.md) or
[TypeScript](https://docs.sovara-labs.com/sdks/typescript/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.