Skip to content

SDKs

Two hand-crafted, idiomatic clients — Python and TypeScript — wrap the Agents API so you compose agents in code, not JSON. For every other language, we generate a client from the same OpenAPI spec that powers this reference, so it never drifts from the API.

Preview — packages publish at launch

The telbox (PyPI) and @telbox/sdk (npm) packages are at 0.1.0 and are not on the public registries yet — they publish when the external API-key path (apikey_auth_enabled) flips on at launch. Until then the source lives in the repo (sdks/python/, sdks/typescript/); point the client's base URL at your developer preview and authenticate with a developer session JWT (the same one the console mints over email + OTP). The snippets below are written against the post-launch tb_live_… key flow.

  • Python

    pip install telbox — sync + async TelboxClient, a typed ir builder, typed errors, and automatic retry with backoff.

  • TypeScript

    npm install @telbox/sdk — zero runtime deps (platform fetch); Node ≥ 18, Deno, Bun, and the browser. Injectable fetch for tests.

  • Other languages

    Go, Rust, Ruby, Java, Kotlin, Swift, PHP, C#, and a typed JS-fetch client — generated on demand from the OpenAPI spec with openapi-generator.

At a glance

Python TypeScript
Install pip install telbox npm install @telbox/sdk
Import from telbox import TelboxClient, ir import { TelboxClient, ir } from "@telbox/sdk"
Package version 0.1.0 (unpublished — see above) 0.1.0 (unpublished — see above)
Runtime Python ≥ 3.9 Node ≥ 18 · Deno · Bun · browser
Base URL https://api.telbox.ai (override with base_url) https://api.telbox.ai (override with baseUrl)
Async AsyncTelboxClient (async with) native — every method returns a Promise

Both wrap the same surface: the base URL is https://api.telbox.ai, every path is under /v1, and every request carries Authorization: Bearer tb_live_…. The API reference is generated from the Agents OpenAPI spec (version 2026-06-14).

Quickstart

Install a curated template, preview it deterministically (no LLM, no side effects), then test-run it in the safe sandbox — the same loop as Getting Started, in your language of choice.

pip install telbox

from telbox import TelboxClient, ir

tb = TelboxClient(api_key="tb_live_…")     # base_url defaults to api.telbox.ai

# Install a curated template — or build from a typed IR with ir.agent(...)
agent = tb.install_template("vip-watcher")
print(agent.id, agent.identity_fingerprint)

# Deterministic preview: what it WOULD do — no LLM, no side effects
preview = tb.dry_run_agent(agent.id)
print(preview.effects, preview.warnings)

# Safe sandbox run: writes propose (mint a confirm token) but never auto-execute
run = tb.test_run(agent.id, "What's open this week?")
print(run.ok, run.answer, run.trace)

Async mirror

from telbox import AsyncTelboxClient mirrors the sync client — every method is await-able; use it as an async with context manager.

npm install @telbox/sdk

import { TelboxClient, ir } from "@telbox/sdk";

const tb = new TelboxClient({ apiKey: "tb_live_…" });   // baseUrl defaults to api.telbox.ai

// Install a curated template — or build from a typed IR with ir.agent(...)
const agent = await tb.installTemplate("vip-watcher");
console.log(agent.id, agent.identityFingerprint);

// Deterministic preview: what it WOULD do — no LLM, no side effects
const preview = await tb.dryRunAgent(agent.id);
console.log(preview.effects, preview.warnings);

// Safe sandbox run: writes propose (mint a confirm token) but never auto-execute
const run = await tb.testRun(agent.id, "What's open this week?");
console.log(run.status, run.answer, run.trace);

Testable by injection

The client takes an injectable fetch (new TelboxClient({ apiKey, fetch })), so you can unit-test your integration with no network.

Build agents in code

Both SDKs ship an ir builder for the typed AgentDefinitionIR, so triggers, steps, argument bindings, and authority guards are typed at the call site instead of hand-written JSON. Argument bindings say where each tool argument's value comes from — literal, from_trigger/fromTrigger, from_step/fromStep, or prompt. See Agents & the IR and Authority.

Not using an SDK?

The API is plain REST + JSON with Bearer auth, so any HTTP client works — the OpenAPI spec is the contract and the curl quickstart shows the raw calls. To scaffold a typed client for another language, see Other languages.