# SDK Overview

> The official inference shell SDKs for Python, JavaScript/TypeScript, and Swift.

**URL:** https://inference.sh/docs/api/sdk/overview
**Last updated:** 2026-10-11

---

The official inference shell SDKs for Python, JavaScript/TypeScript, and Swift.

All SDKs unwrap the `{ "data", "messages" }` response envelope and raise RFC 9457 errors — see [REST overview — response format](/docs/api/rest/overview#response-format).

---

## Installation

<div data-type="codegroup">

```python
# Installation
pip install inferencesh

# With async support
pip install inferencesh[async]
```

```typescript
// Installation
npm install @inferencesh/sdk
// or yarn add @inferencesh/sdk
// or pnpm add @inferencesh/sdk
```

```swift
// Installation: Package.swift
.package(url: "https://github.com/inference-sh/sdk-swift", from: "0.1.0")
// target dependency: .product(name: "InferenceSDK", package: "sdk-swift")
// or in Xcode: File → Add Package Dependencies…
```

</div>

---

## Quick Start

<div data-type="codegroup">

```python Python
from inferencesh import inference

client = inference(api_key="inf_your_key")

# Run an app and wait for result
result = client.tasks.run({
    "app": "infsh/flux",
    "input": {"prompt": "A sunset over mountains"}
})

print(result["output"])
```

`client.run()` is a legacy alias for `client.tasks.run()`. See [Python SDK](/docs/api/sdk-python#client-api) for the Python namespaces available today.

```typescript JavaScript
import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

const result = await client.run({
  app: 'infsh/flux',
  input: { prompt: 'A sunset over mountains' }
});

console.log(result.output);
```

```swift Swift
import InferenceSDK

let client = InferenceClient(apiKey: "inf_your_key")

// Run an app and wait for the result
let task = try await client.tasks.run(ApiAppRunRequest(
    app: "infsh/flux",
    input: ["prompt": "A sunset over mountains"]
))

print(task.output)
```

</div>

---

## Client structure

All SDKs expose namespaced APIs on the client. The JavaScript SDK covers the full REST surface; Python currently ships the core run/chat namespaces; Swift ships tasks, files, agents, chats, apps, sockets, and search.

| Namespace | Purpose | Python | JavaScript | Swift |
|-----------|---------|:------:|:----------:|:-----:|
| `tasks` | Run, get, cancel, list, and stream app tasks | ✓ | ✓ | ✓ |
| `files` | Upload, list, get, and delete files | ✓ | ✓ | ✓ |
| `agents` | Create agents and send messages | ✓ | ✓ | ✓ |
| `sockets` / `live()` | Run a [stream function](/docs/extend/streaming#calling-a-live-function) and hold its socket | ✓ (async client) | ✓ | ✓ |
| `sessions` | List, inspect, keepalive, and end sessions | ✓ | ✓ | — |
| `apps` | List, create, and manage deployed apps | — | ✓ | ✓ |
| `chats` | List and manage chats; `getTrace()` for agent observability | — | ✓ | ✓ (no `getTrace`) |
| `engines` | List, drain, update, and extend cloud engine rentals | — | ✓ | — |
| `flows` / `flowRuns` | Flow definitions (`flows.updateVisibility`) and run lifecycle (`flowRuns.create`, `stream`, `streamTasks`) | — | ✓ | — |
| `search` | Programmatic `/suggest` and `/search` | — | ✓ | ✓ |
| `knowledge` / `skills` | Knowledge and skill CRUD | — | ✓ | — |
| `teams`, `secrets`, `apiKeys`, `credentials`, `projects`, `mcpServers` | Workspace and connector management | — | ✓ | — |

Top-level `run()` / `uploadFile()` (JavaScript) and `run()` / `upload_file()` (Python) are legacy aliases for `tasks.run()` and `files.upload()`.

When a namespace is JavaScript-only, call the equivalent [REST endpoint](/docs/api/rest/overview) from Python or Swift until the SDK adds helpers.

### Inspect and observability (JavaScript)

| Method | REST endpoint | Description |
|--------|---------------|-------------|
| `client.tasks.getLogs(id)` | `GET /tasks/{id}/logs` | Structured task log lines |
| `client.tasks.getTimings(id)` | `GET /tasks/{id}/timings` | Phase durations from status events |
| `client.tasks.getTelemetry(id)` | `GET /tasks/{id}/telemetry` | Time-series CPU, RAM, GPU, and volume samples |
| `client.chats.getTrace(id)` | `GET /chats/{id}/trace` | Agent execution graph (nodes, edges, step counts) |

→ [Tasks REST API](/docs/api/rest/tasks) · [Agents REST API](/docs/api/rest/agents) · [Observability](/docs/runtime/observability)

Use **inferencesh** ≥ v0.7.8 or **@inferencesh/sdk** ≥ v0.6.12 for the full JavaScript REST surface (knowledge, workspaces, search, task observability helpers, `agents.getA2ACard`, and related namespaces).

→ [Python SDK](/docs/api/sdk-python#client-api) · [JavaScript SDK](/docs/api/sdk-javascript#client-api) · [Swift SDK](/docs/api/sdk-swift#client-api) · [REST overview — response format](/docs/api/rest/overview#response-format)

---

## What's in the SDK?

### Running Apps
Execute AI apps on inference shell infrastructure.
- [Running Apps](/docs/api/sdk/running-apps) — Basic task execution
- [Streaming](/docs/api/sdk/streaming) — Real-time progress updates
- [Files](/docs/api/sdk/files) — File uploads and downloads

### Agent SDK
Build and interact with AI agents programmatically.
- [Agent SDK Overview](/docs/api/agent/overview) — Introduction
- [Template Agents](/docs/api/agent/template) — Use existing agents
- [Ad-hoc Agents](/docs/api/agent/adhoc) — Create agents on-the-fly
- [Building Tools](/docs/api/agent/tools) — Define custom tools (client, app, HTTP/call, webhook, MCP)

### Server Proxy
Protect API keys in frontend applications.
- [Server Proxy](/docs/api/sdk/server-proxy) — Proxy setup for all frameworks
- [Vercel Deployment](/docs/api/sdk/vercel) — Deploy with Vercel integration

### Building Apps
Create your own apps to run on inference shell.
→ See [Extend overview](/docs/extend/overview) or [Extending Apps](/docs/extend/extending-apps) for the app development guide.

---

## Environment Variables

<div data-type="codegroup">

```python Python
from inferencesh import inference

client = inference()  # reads INFERENCE_API_KEY
```

```typescript JavaScript
import { inference } from '@inferencesh/sdk';

const client = inference({ 
  apiKey: process.env.INFERENCE_API_KEY 
});
```

```swift Swift
import Foundation
import InferenceSDK

let client = InferenceClient(
    apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? ""
)
```

</div>

---

## TypeScript Support

The JavaScript SDK includes full TypeScript definitions:

```typescript
import type { Task, ApiTaskRequest, InferenceConfig } from '@inferencesh/sdk';
```

---

## Browser & Node.js

The JavaScript SDK works in both environments:

```typescript
// Node.js (CommonJS, Node 22.12+, @inferencesh/sdk >= 0.23.0)
const { inference } = require('@inferencesh/sdk');

// ES Modules / TypeScript
import { inference } from '@inferencesh/sdk';

// Browser (ESM CDN)
import { inference } from 'https://esm.sh/@inferencesh/sdk';
```

> **Note**: Never expose API keys in client-side code. Use the [Server Proxy](/docs/api/sdk/server-proxy) in production.

---

## Requirements

<div data-type="tabs">
<div data-type="tab" title="Python">

- Python 3.8+
- `requests` for sync client
- `aiohttp` for async client (optional)

</div>
<div data-type="tab" title="JavaScript">

- Node.js 22.12.0+ (npm `engines`; required by the `eventsource` 5.x dependency used for SSE streaming)
- Modern browsers with `fetch` support

</div>
<div data-type="tab" title="Swift">

- Swift 5.9+
- iOS 17+ / macOS 14+
- Linux (Foundation + FoundationNetworking)

</div>
</div>

---

## Language references

- [**JavaScript SDK**](/docs/api/sdk-javascript) — Full TypeScript/JavaScript API
- [**Python SDK**](/docs/api/sdk-python) — Full Python API
- [**Swift SDK**](/docs/api/sdk-swift) — Full Swift API (iOS, macOS, Linux)