# SDKs

> Official client libraries for Rust, Python, and TypeScript — typed clients, async APIs, SSE streaming with automatic reconnection.

Source: <https://everruns.com/docs/features/sdk/>

The Everruns SDKs are official client libraries for building agent applications. Rust, Python, and TypeScript with a consistent API across all three.

What the SDKs handle for you:

* **Consistent API** across languages
* **Async/await patterns** throughout
* **SSE streaming** with automatic reconnection, heartbeat-based stale detection, and `since_id` resumption
* **Typed models** generated from the OpenAPI spec
* **Sub-client organization** (`agents`, `sessions`, `messages`, `events`, `filesystem`, …)

For a hands-on lesson, see [Build your first agent](https://everruns.com/docs/tutorials/building-agents-using-sdk/) or the minimal [Run an Agent](https://everruns.com/docs/tutorials/run-an-agent/) notebook.

## Install

* Rust

  Requires Rust 1.70+

  ```bash
  cargo add everruns-sdk
  ```

* Python

  Requires Python 3.10+

  ```bash
  pip install everruns-sdk
  ```

* TypeScript

  Requires Node.js 18+

  ```bash
  npm install @everruns/sdk
  ```

## Authenticate

All SDKs read `EVERRUNS_API_KEY` (a personal access token, `evr_pat_...`) and `EVERRUNS_API_URL` from the environment. Always set the URL: use `https://app.everruns.com/api` for [Everruns Cloud](https://app.everruns.com), or `http://<your-host>/api` for a self-hosted Platform. Create the token under **Settings** > **Personal Access Tokens**.

* Rust

  ```rust
  use everruns_sdk::Everruns;


  let client = Everruns::from_env()?; // EVERRUNS_API_KEY + EVERRUNS_API_URL
  let client = Everruns::with_base_url("evr_pat_...", "https://app.everruns.com/api")?;
  ```

* Python

  ```python
  from everruns_sdk import Everruns


  client = Everruns()  # EVERRUNS_API_KEY + EVERRUNS_API_URL
  client = Everruns(api_key="evr_pat_...", base_url="https://app.everruns.com/api")
  ```

* TypeScript

  ```typescript
  import { Everruns } from "@everruns/sdk";


  const client = new Everruns(); // EVERRUNS_API_KEY + EVERRUNS_API_URL
  const client = new Everruns({ apiKey: "evr_pat_...", baseUrl: "https://app.everruns.com/api" });
  ```

## API coverage

| Resource            | Operations                                                                             |
| ------------------- | -------------------------------------------------------------------------------------- |
| **Agents**          | Create, list, get, apply, copy, delete, import, export, stats, versions, health checks |
| **Sessions**        | Create, list, get, delete, cancel, resume, pin, export, set secrets, budgets           |
| **Messages**        | Create, list, submit client-side tool results                                          |
| **Events**          | List, stream (SSE)                                                                     |
| **Capabilities**    | List, get, guardrail dry runs                                                          |
| **Harnesses**       | Create, list, search, get, update, delete                                              |
| **Models**          | List, get                                                                              |
| **Workspaces**      | Create, list, get, update, delete                                                      |
| **Workspace files** | List, read, create, update, delete, move, copy, grep, stat                             |
| **Memories**        | Create, list, get, update, delete, sync, file operations                               |
| **Budgets**         | Create, list, get, update, delete, top up, ledger, check                               |
| **Connections**     | Set, list, remove                                                                      |

Everything else (providers, MCP servers, organizations, schedules) is available through the [REST API](https://everruns.com/docs/api/).

## Error handling

| Error type            | Description                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationError` | Invalid or missing API key (Python, TypeScript)                                                                        |
| `NotFoundError`       | Resource not found (Python, TypeScript)                                                                                |
| `RateLimitError`      | Rate limit exceeded (Python, TypeScript)                                                                               |
| `ApiError`            | General API error; Rust uses `Error::Api { status, .. }` for all HTTP errors and `Error::Auth` for credential problems |

* Rust

  ```rust
  use everruns_sdk::Error;


  match client.agents().get("invalid-id").await {
      Ok(agent) => println!("Found: {}", agent.name),
      Err(Error::Api { status: 404, message, .. }) => println!("Not found: {}", message),
      Err(Error::Auth(msg)) => println!("Auth error: {}", msg),
      Err(e) => println!("Other error: {}", e),
  }
  ```

* Python

  ```python
  from everruns_sdk import NotFoundError, AuthenticationError


  try:
      agent = await client.agents.get("invalid-id")
  except NotFoundError as e:
      print(f"Not found: {e}")
  except AuthenticationError as e:
      print(f"Auth error: {e}")
  ```

* TypeScript

  ```typescript
  import { NotFoundError, AuthenticationError } from "@everruns/sdk";


  try {
    const agent = await client.agents.get("invalid-id");
  } catch (e) {
    if (e instanceof NotFoundError) {
      console.log(`Not found: ${e.message}`);
    } else if (e instanceof AuthenticationError) {
      console.log(`Auth error: ${e.message}`);
    }
  }
  ```

## Do something

* [Build your first agent](https://everruns.com/docs/tutorials/building-agents-using-sdk/) — guided tutorial.
* [Stream events with the SDK](https://everruns.com/docs/how-to/stream-events/) — common streaming patterns.
* [Handle errors and cancel turns](https://everruns.com/docs/how-to/handle-errors-and-cancellation/) — graceful failure paths.
* [Orchestrate multi-agent pipelines](https://everruns.com/docs/how-to/orchestrate-multi-agent-pipelines/) — chain agents together.

## See also

* [API reference](https://everruns.com/docs/api/) — every endpoint, generated from OpenAPI.
* [Event Reference](https://everruns.com/docs/event-reference/) — every event type.
* [GitHub Repository](https://github.com/everruns/sdk) — source code and examples.

## Overview video

[Everruns SDK Overview](https://www.youtube.com/embed/1FfGKUTzBzA)