Skip to content

Telbox Agents

Build cryptographically-verified agents that run as participants in an end-to-end-encrypted messenger. An agent has its own identity, signs the messages it sends, runs on triggers you choose, acts within an authority leash you set, and reaches the world through MCP — both directions.

You build one by installing a template, describing it in words, or composing a typed AgentDefinitionIR — then preview it, test it safely, and let it run.

Preview

The external API is gated behind apikey_auth_enabled in production until launch. Until then, point your client's base URL at the developer preview.

  • Getting Started

    Get a key, build your first agent, dry-run it, test it — in five minutes, in curl, Python, or TypeScript.

  • Agents & the IR

    What an agent is, the typed AgentDefinitionIR, and the verified-principal identity that makes "from Agent X" provable.

  • Authority & autonomy

    The leash: draft_only → ask_before_action → auto_act_limited. Per-tool limits, and an honest account of the injection posture.

  • Preview, test, run

    Dry-run (no LLM, no side effects), test-run (safe sandbox), and the production trigger that actually acts.

  • MCP — both directions

    Expose your agent as an MCP server, and consume external MCP servers through the broker.

  • SDKs

    Idiomatic, typed Python and TypeScript clients — plus 9 more generated languages.

At a glance
Base URL https://api.telbox.ai
Version prefix /v1 (every endpoint)
Auth Authorization: Bearer tb_live_… (API key)
Content type application/json
Spec OpenAPI 3.1 — Agents API
SDKs Python · TypeScript · 9 generated

The shape of it

from telbox import TelboxClient, ir

tb = TelboxClient(api_key="tb_live_…")

agent = tb.create_agent(ir.agent(
    "Nudge non-repliers",
    persona="Each Monday, nudge whoever still owes a reply — gently.",
    triggers=[ir.schedule("0 9 * * 1")],
    steps=[
        ir.tool("s1", "get_tasks", status=ir.literal("open")),
        ir.tool("s2", "create_reminder", title=ir.prompt("follow up")),
    ],
    guards={"reminders": ir.guard("auto_act_limited")},
))

print(tb.dry_run_agent(agent.id).effects)   # what it WOULD do — no side effects

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

const tb = new TelboxClient({ apiKey: "tb_live_…" });

const agent = await tb.createAgent(ir.agent("Nudge non-repliers", {
  persona: "Each Monday, nudge whoever still owes a reply — gently.",
  triggers: [ir.schedule("0 9 * * 1")],
  steps: [
    ir.tool("s1", "get_tasks", { status: ir.literal("open") }),
    ir.tool("s2", "create_reminder", { title: ir.prompt("follow up") }),
  ],
  guards: { reminders: ir.guard("auto_act_limited") },
}));

console.log((await tb.dryRunAgent(agent.id)).effects);

export TELBOX=https://api.telbox.ai
export KEY=tb_live_…

curl -X POST $TELBOX/v1/agents \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Nudge","triggers":[{"kind":"schedule","cron":"0 9 * * 1"}],
       "steps":[{"id":"s1","type":"tool","tool":"get_tasks"},
                {"id":"s2","type":"tool","tool":"create_reminder",
                 "args":{"title":{"prompt":"follow up"}}}],
       "guards":{"capabilities":{"reminders":{"level":"auto_act_limited"}}}}'

The moat

The defensible core is the verified agent principal: each agent has its own Ed25519 identity and signs the messages it sends, so recipients get a tap-to-verify badge and impersonation is cryptographically impossible — not merely discouraged. Everything else (templates, build-by-talking, voice, MCP, marketplace) sits on top of that, inside Telbox's E2E-encrypted, no-train, consent-based substrate.