all systems normal · status.trellisagents.example v2.3.0 · tokens pass through at $0 margin

docs / quickstart

First traced run in ~10 minutes.

Everything below runs on the free dev tier: 1,000 runs a month, sampled traces, no card. The dev sandbox traces everything but executes tools against mocks, so you can't hurt anything while you learn.

1 · Install & authenticate

The SDK defines agents; the CLI runs, evaluates, and deploys them. Both talk to the same Runs API, so anything the CLI does you can script.

shell

# TypeScript

npm i @trellis/sdk && npm i -g @trellis/cli

# Python

pip install trellis-agents

# authenticate — opens the console, drops a key in ~/.trellis

trellis login

TypeScript and Python SDKs are equivalent — pick your codebase's language

2 · Define an agent

An agent is configuration, not a framework takeover: a model, instructions, a tool list, and — non-negotiable in production — a budget and a failure path. Note that the argument schema on the tool is itself a guardrail: an approval above $200 is rejected by the runtime before the handler runs, no matter how persuasive the model's reasoning was.

// agents/expense-checker.ts import { agent, tool, schema } from "@trellis/sdk"; const ReceiptArgs = schema({ receiptId: "string", amountUsd: { type: "number", max: 200 }, // schema IS a guardrail }); const approveExpense = tool("expenses.approve", { schema: ReceiptArgs, handler: async (args) => expenseApi.approve(args), }); export const expenseChecker = agent("expense-checker", { model: "economy-30b", instructions: "Check the receipt against policy. Approve only if compliant.", tools: [approveExpense], budget: { tokens: 20_000, usd: 0.02, wallClock: "30s" }, onFail: "escalate", });

3 · Run it, read the trace

trellis dev starts a sandbox: every span is traced and priced exactly like production, but tool handlers hit mocks. The per-span dollar amounts are real arithmetic on the token counts — get in the habit of reading them now, before the volumes get interesting.

trellis — zsh

$ trellis dev agents/expense-checker.ts

✓ manifest valid · 1 tool · schema guardrail active

✓ dev sandbox up — runs are traced but sandboxed (no real side effects)

$ trellis run expense-checker --input '{"receiptId":"rcpt_8812"}'

run_01JD41 started…

├─ model plan — 1,204 in / 96 out tok · 480ms · $0.00024

├─ tool expenses.approve — ok (sandboxed) · 120ms

└─ model confirm — 890 in / 74 out tok · 390ms · $0.00018

✓ resolved in 1.2s · 2,264 tokens · $0.00042

trace: console.trellisagents.example/runs/01JD41

a sandboxed run: 2 model calls, 1 tool call, $0.00042 total

Open the trace link and click through the spans. What the model saw, what it said, what the tool returned, what it cost — that trace is the primary debugging artifact for everything you'll build on Trellis.

4 · Gate it, ship it

Before the first deploy, wire the eval gate — even with a two-suite starter set. The gate is a normal exit-code command, so it drops into any CI. Deploys that regress below your thresholds fail loudly in the pipeline instead of quietly in production.

# trellis.yaml — gate deploys on your eval suites

eval:

suites: [expense-policy, tone-rubric]

thresholds:

expense-policy: { min_pass: 0.98 }

$ trellis eval --gate && trellis deploy expense-checker

From here: add classifier screens in Guardrails, grow your eval sets from flagged traces (see eval-driven agent development), and when you're ready to size a production fleet, the configurator prices it in the open.