Templates¶

Templates are the low-risk way to stand up a working agent. Each one is a hand-authored, hand-tested agent definition (an IR) composed over real in-house tools, validated at import against the live tool registry and the closed trigger/authority vocabularies. Installing a template is one call — it mints a grant and creates a real agent in your workspace that you can immediately dry-run, test-run, edit, or revoke. There are ten curated templates today; this guide lists them and shows how to install and customize one.

Templates vs. building from scratch

A template carries value with zero NL-compiler risk — natural language only fills in parameters (a name, a persona, a filter). If you want full control, build an agent from an IR instead, or compile from natural language. But start here: every template instantiates a real, useful agent, not a shell.

The ten templates¶

Each template composes the tools listed below, fires on the given trigger, and ships with a default authority for any tool that writes or reaches outside Telbox. Read-only templates have no authority guard at all (nothing to gate).

ID	What it does	Tools	Trigger	Default authority
`daily-thread-summary`	Posts a daily recap of a thread's decisions and open questions.	`search_messages`	Schedule — daily at 18:00 (`0 18 * * *`)	`thread_replies`: draft only
`nudge-non-repliers`	Weekly gentle reminders to whoever still owes a reply.	`get_tasks`, `create_reminder`	Schedule — Mondays at 09:00 (`0 9 * * 1`)	`reminders`: auto-act (limited)
`vip-watcher`	Turns messages from important people into confirm-first tasks.	`get_message`, `create_task`	On message arrival	`tasks`: ask before action
`meeting-scheduler`	On request, finds free time and proposes slots in the thread.	`find_free_slot`, `propose_meeting_slots`	Manual	`calendar`: ask before action
`morning-brief`	Each morning, summarizes the last 24h of activity and what's due today.	`get_today_brief`, `get_tasks`	Schedule — daily at 07:00 (`0 7 * * *`)	None (read-only)
`promise-keeper`	End of day, reminds you of promises you made that are still open.	`get_promises`, `create_reminder`	Schedule — daily at 17:00 (`0 17 * * *`)	`reminders`: ask before action
`web-researcher`	On request, searches the live web and answers with cited results.	`web_search`	Manual	None (read-only)
`email-drafter`	Drafts a reply email from an incoming message — you approve before send.	`get_message`, `compose_email_draft`	On message arrival	`email`: draft only
`calendar-concierge`	On request, shows your week and finds open time for a meeting.	`list_calendar_events`, `find_free_slot`	Manual	`calendar`: draft only
`people-recap`	On request, summarizes your recent history with a specific person.	`list_people`, `person_summary`	Manual	None (read-only)

Authority is enforced, not just advertised

The default authority is a hard gate on what a template's write tools may do — draft_only never sends, ask_before_action requires a confirm, and only auto_act_limited acts on its own within limits. These map to the same authority gradient documented in Agents. You can change a template's authority by forking its IR and re-creating.

Browse the catalog programmatically with GET /v1/agent-templates, which returns each template's id, title, description, and category:

curlPythonTypeScript

curl https://api.telbox.ai/v1/agent-templates \
  -H "Authorization: Bearer $TELBOX_API_KEY"

from telbox import TelboxClient

tb = TelboxClient(api_key="tb_live_…")
for t in tb.templates():
    print(t.id, "—", t.description)

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

const tb = new TelboxClient({ apiKey: "tb_live_…" });
for (const t of await tb.templates()) {
  console.log(t.id, "—", t.description);
}

Install a template¶

Installing is a single call to POST /v1/agents/from-template with a template_id. It returns the full agent detail (its IR, identity fingerprint, triggers, permissions, and consent state) with HTTP 201.

curlPythonTypeScript

curl -X POST https://api.telbox.ai/v1/agents/from-template \
  -H "Authorization: Bearer $TELBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "vip-watcher"}'

from telbox import TelboxClient

tb = TelboxClient(api_key="tb_live_…")
agent = tb.install_template("vip-watcher")
print(agent.id, agent.name, agent.triggers)

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

const tb = new TelboxClient({ apiKey: "tb_live_…" });
const agent = await tb.installTemplate("vip-watcher");
console.log(agent.id, agent.name, agent.triggers);

Unknown template IDs 404

An unrecognized template_id returns 404 template_not_found. Use one of the ten IDs from the table above (or whatever GET /v1/agent-templates returns live). Installs are rate-limited per developer; see Rate Limits & Quotas.

Installing creates a real agent¶

The returned object is a fully-fledged agent, identical to one built from a raw IR. Once installed, you can drive its whole lifecycle:

Dry-run — POST /v1/agents/{id}/dry-run previews every step it would take, each write's real authority decision, and whether it'd auto-reply — deterministically, with no LLM call and zero side effects. Use it before you trust the agent.
Test-run — POST /v1/agents/{id}/test-run runs it once against a sample prompt in a safe sandbox (write tools propose but never auto-execute) and persists a durable run with a full trace you can read back via GET /v1/agents/{id}/runs.
Inspect — GET /v1/agents/{id} returns the agent's persona, IR, permissions, triggers, and verified identity fingerprint.
Revoke — DELETE /v1/agents/{id} tombstones the definition, revokes its grants, and disables its triggers.

curlPythonTypeScript

AGENT=$(curl -s -X POST https://api.telbox.ai/v1/agents/from-template \
  -H "Authorization: Bearer $TELBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "vip-watcher"}' | jq -r .id)

# Side-effect-free preview of what it would do
curl -X POST "https://api.telbox.ai/v1/agents/$AGENT/dry-run" \
  -H "Authorization: Bearer $TELBOX_API_KEY"

# One sandboxed run against a sample prompt
curl -X POST "https://api.telbox.ai/v1/agents/$AGENT/test-run" \
  -H "Authorization: Bearer $TELBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A note just arrived from the CEO — is there an action?"}'

from telbox import TelboxClient

tb = TelboxClient(api_key="tb_live_…")
agent = tb.install_template("vip-watcher")

# Deterministic preview — no LLM, no side effects
preview = tb.dry_run_agent(agent.id)
print(preview.effects, preview.would_auto_reply, preview.warnings)

# One sandboxed run, persisted with a full trace
run = tb.test_run(agent.id, "A note just arrived from the CEO — is there an action?")
print(run.status, run.answer)

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

const tb = new TelboxClient({ apiKey: "tb_live_…" });
const agent = await tb.installTemplate("vip-watcher");

// Deterministic preview — no LLM, no side effects
const preview = await tb.dryRunAgent(agent.id);
console.log(preview.effects, preview.wouldAutoReply, preview.warnings);

// One sandboxed run, persisted with a full trace
const run = await tb.testRun(
  agent.id,
  "A note just arrived from the CEO — is there an action?",
);
console.log(run.status, run.answer);

Dry-run vs. test-run

Dry-run is a deterministic prediction — it never calls the model and changes nothing. Test-run actually executes the agent's loop once in a sandbox (no authority_resolver, so writes propose rather than auto-act) and records a durable run you can replay. Reach for dry-run to validate structure; test-run to see real output. Both are detailed in Agents.

Fork and customize a template¶

A template install isn't a black box — the installed agent exposes its full IR. Fetch the agent, read its .ir, edit the JSON (rename it, change a trigger, raise or lower an authority guard, add a step), and re-create it as a new agent with POST /v1/agents. The original is untouched, so you can revoke whichever you don't keep.

curlPythonTypeScript

# 1. Pull the installed agent's IR
curl -s "https://api.telbox.ai/v1/agents/$AGENT" \
  -H "Authorization: Bearer $TELBOX_API_KEY" | jq .ir > my-agent.json

# 2. Edit my-agent.json (name, triggers, guards, steps) …

# 3. Re-create as a new, customized agent
curl -X POST https://api.telbox.ai/v1/agents \
  -H "Authorization: Bearer $TELBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @my-agent.json

from telbox import TelboxClient

tb = TelboxClient(api_key="tb_live_…")

# 1. Fork the template's IR off an installed agent
agent = tb.install_template("nudge-non-repliers")
ir = dict(agent.ir)  # the persisted definition

# 2. Customize it
ir["name"] = "Nudge — design team only"
ir["guards"]["capabilities"]["reminders"]["level"] = "ask_before_action"

# 3. Validate before committing, then re-create
print(tb.dry_run(ir).warnings)
custom = tb.create_agent(ir)
print(custom.id)

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

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

// 1. Fork the template's IR off an installed agent
const agent = await tb.installTemplate("nudge-non-repliers");
const ir = { ...(agent.ir as Record<string, unknown>) };

// 2. Customize it
(ir as any).name = "Nudge — design team only";
(ir as any).guards.capabilities.reminders.level = "ask_before_action";

// 3. Validate before committing, then re-create
console.log((await tb.dryRun(ir as any)).warnings);
const custom = await tb.createAgent(ir as any);
console.log(custom.id);

Dry-run your fork first

A customized IR is re-validated against the live tool registry and the closed trigger/authority vocabularies on POST /v1/agents — an unknown tool, trigger kind, or authority level is rejected. Run dry-run on the edited IR first to catch problems and preview the new behavior with no side effects.

Next steps¶

Agents — the full model: identity, triggers, the authority gradient, and the run lifecycle.
Authentication — minting and scoping the developer API key these calls use.
Rate Limits & Quotas — the per-developer write budget that install, create, dry-run, and test-run share.