Python SDK¶

The official Python client — pip install telbox. Idiomatic, typed, retrying, with an ir builder so you compose agents in code, not JSON.

from telbox import TelboxClient, ir

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

agent = tb.install_template("vip-watcher")        # or tb.create_agent(ir.agent(...))
preview = tb.dry_run_agent(agent.id)              # no LLM, no side effects
run = tb.test_run(agent.id, "What's open this week?")   # safe sandbox
print(run.ok, run.answer, run.trace)

Async

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

Building agents¶

telbox.ir builds the AgentDefinitionIR. Argument bindings say where each tool argument's value comes from:

binding	meaning
`ir.literal(v)`	a fixed value
`ir.from_trigger("message.message_id")`	from the firing event
`ir.from_step("s1.result.hits[0].id")`	from an earlier step's result
`ir.prompt("hint")`	let the agent decide

Triggers: ir.schedule(cron), ir.on_message(mention_required=True, content_type="text"), ir.manual(). Guards: ir.guard("auto_act_limited", approved_domains=["acme.com"]). See Agents & the IR and Authority.

Methods¶

Method	Endpoint
`templates()`	`GET /v1/agent-templates`
`tools()`	`GET /v1/agent-tools`
`compile(text)`	`POST /v1/agents/compile`
`dry_run(ir)` / `dry_run_agent(id)`	`POST /v1/agents[/{id}]/dry-run`
`create_agent(ir)`	`POST /v1/agents`
`install_template(template_id)`	`POST /v1/agents/from-template`
`list_agents()` / `get_agent(id)` / `revoke_agent(id)`	`GET`/`GET`/`DELETE /v1/agents[/{id}]`
`test_run(id, prompt)`	`POST /v1/agents/{id}/test-run`
`list_runs(id)` / `get_run(id, run_id)`	`GET /v1/agents/{id}/runs[/{run_id}]`
`create_api_key()`	`POST /v1/agents/api-keys`
`agent_mcp_call(id, name, args)`	`POST /v1/agents/{id}/mcp`

Errors¶

Every error subclasses telbox.TelboxError: AuthError (401/403), NotFoundError (404), ValidationError (422), RateLimited (429, with .retry_after), APIError (other). Each carries .status, .code, .body. The client retries 429/5xx with backoff (max_retries, default 2).

Full README + source: sdks/python/ in the repo.