Chapter 8 of 8
Guarded tools and teams
Put a human in the loop with one word. Compose agents with the tools you already know: sub-agents, spawn and |>.
tin run examples/agents/04-approval.tin// `guarded tool fn` puts a human in the loop.
//
// Before a guarded tool runs, the agent loop pauses and the runtime asks for
// approval. If the answer is no, the tool never runs: the model is told the
// call was denied and carries on without it.
//
// tin run examples/agents/04-approval.tin asks you (or denies, if not a terminal)
// tin run examples/agents/04-approval.tin --yes approves everything
/// List the files in the project.
tool fn listFiles(): string[] => ["notes.txt", "draft.md", "old-backup.zip"]
/// Permanently delete a file.
guarded tool fn deleteFile(path: string): string => "deleted {path}"
agent Janitor {
model: "mock"
system: "You tidy up the project. Ask before deleting anything important."
tools: [listFiles, deleteFile]
on toolResult(name, output, ok) => print(" {name} -> {output}")
}
fn main() {
print(Janitor("use listFiles"))
print(Janitor("deleteFile 'old-backup.zip'"))
// Plain code can call a guarded tool too, but only through `approve`, which
// shows a person the exact call first. Calling deleteFile(...) directly is a
// compile error.
match approve deleteFile("draft.md") {
Ok(msg) => print(msg)
Err(why) => print("not done: {why}")
}
} listFiles -> ["notes.txt","draft.md","old-backup.zip"]
mock: ["notes.txt","draft.md","old-backup.zip"]
deleteFile -> Tool call denied by the user. Do not retry it; continue without it.
mock: error: Tool call denied by the user. Do not retry it; continue without it.
not done: denied: deleteFile In the tests nobody is at the keyboard, so the guarded call is denied and the model carries on without it.
A guarded tool fn never runs without approval. If the answer is no, the model is
told the call was denied. tin run --yes approves everything.
The compiler checks this before anything runs. A guarded tool can only be reached through an
agent that was given it, so calling it straight from main, or through a plain tool, is a
compile error. tin caps prints what each agent can reach.
tin run examples/agents/07-capabilities.tin// Capabilities are checked by the compiler, before anything runs.
//
// `guarded tool fn` means "a person approves every call". The compiler proves
// that on every path: the only way into `wireMoney` is an agent that was given
// it, and the agent loop asks first. Each of these is a compile error:
//
// fn main() { wireMoney("bob", 5) } // skips approval
// tool fn refund(to: string): string => wireMoney(to, 1)
// // an agent could reach it unasked
// agent Clerk { tools: [balance]
// on text(t) => print(wireMoney("me", 1)) } // not given, and skips approval
//
// See what each agent can reach: tin check --caps examples/agents/07-capabilities.tin
/// Look up an account balance.
tool fn balance(account: string): int => 120
/// Move money to another account. A person approves every call.
guarded tool fn wireMoney(to: string, amount: int): string {
// code inside a guarded tool already has approval, so it may call others
audit("wire {amount} to {to}")
}
fn audit(line: string): string {
print(" audit: {line}")
"sent"
}
/// Answers questions about the account. Read-only.
agent Teller {
model: "mock"
tools: [balance]
}
/// Can move money, and delegates questions to the Teller.
agent Banker {
model: "mock"
tools: [Teller, wireMoney]
on toolCall(name, input) => print(" {name} {input}")
}
fn main() {
print(Teller("balance of 'savings'"))
// run with --yes to approve; under `tin test` approval is denied
print(Banker("wireMoney 'bob' 5"))
} mock: 120
wireMoney {"to":"bob","amount":5}
mock: error: Tool call denied by the user. Do not retry it; continue without it. Put an agent in another agent's tools list and it becomes a sub-agent. One agent holds one
conversation, so .fresh() makes a copy with an empty history for parallel work.
tin run examples/agents/03-team.tin// Agents compose with everything else in the language:
// - an agent in another agent's `tools` list becomes a tool (a sub-agent)
// - `spawn` runs agents concurrently on the event loop
// - `|>` chains them, because an agent is called like a function
/// Look up the population of a city, in millions.
tool fn population(city: string): float {
sleep(150ms) // pretend this is a slow lookup
match city {
"Istanbul" => 15.7
"Tokyo" => 14.0
"London" => 8.9
_ => 1.0
}
}
/// Knows facts about cities.
agent Researcher {
model: "mock"
tools: [population]
}
/// Rewrites text for a general audience.
agent Editor { model: "mock" }
agent Lead {
model: "mock"
system: "Delegate research to the Researcher."
tools: [Researcher]
on toolCall(name, input) => print(" lead delegates to {name}")
}
fn main() {
// a sub-agent call
print(Lead("ask the Researcher for the population of 'Istanbul'"))
// Three research tasks at once. One agent holds one conversation, so calls
// to the same agent queue up; fresh() makes a copy with an empty history.
let cities = ["Istanbul", "Tokyo", "London"]
let t0 = now()
let tasks = cities.map(c => spawn Researcher.fresh().ask("population of '{c}'"))
for task in tasks { print(await task) }
// one by one would take at least 450ms; in parallel it is about 150ms, so 300ms leaves room for a busy machine
print(if now() - t0 < 300ms { "ran in parallel" } else { "ran one by one" })
// a pipeline of agents
let summary = "population of 'Tokyo'" |> Researcher |> Editor
print(summary)
} lead delegates to Researcher
mock: mock: 15.7
mock: 15.7
mock: 14
mock: 8.9
ran in parallel
mock: mock: 14 All of it together: a planner that answers with a typed Plan, two robots that
each get only their own tools and work in parallel, and one guarded tool. The plan is an ordinary
value, so main can print and check it before anything moves, and
tin caps shows that only the arm can reach scrap, and only with approval.
Its model side comes from a scripted tape, so it runs offline:
tin run examples/agents/08-fleet.tin --replay tests/tapes/agents-08-fleet.json --yes.
tin run examples/agents/08-fleet.tin --replay tests/tapes/agents-08-fleet.json// A fleet: one planner, two workers, and a person who approves the risky part.
//
// The Planner never touches a robot. It answers with a typed Plan, which is an
// ordinary Tin value, so main() can print it, check it and dispatch it before
// anything moves. Rover and Arm each get only their own tools. The compiler
// proves `scrap` (guarded) is reachable only through Arm's agent loop, where
// a person is asked first.
//
// Offline, from a scripted tape: tin run examples/agents/08-fleet.tin --replay tests/tapes/agents-08-fleet.json --yes
// With a real model: tin run examples/agents/08-fleet.tin --trace
type Zone = | Dock | Shelves | Bench
type Crew = | Wheels | Hands
type Step = {
/// Who does it: Wheels (the rover) or Hands (the arm)
crew: Crew
/// One short instruction for that robot
task: string
}
type Plan = {
goal: string
steps: Step[]
}
/// Drive the rover to a zone. Reports the travel time.
tool fn drive(to: Zone): string {
sleep(30ms)
let t = match to { Dock => 40, Shelves => 25, Bench => 10 }
"arrived at {to} after {t}s"
}
/// Count how many of an item are on the shelves.
tool fn stock(item: string): int => if item.contains("filament") { 3 } else { 0 }
/// Pick items with the arm and place them on the bench.
tool fn pick(item: string, quantity: int): string {
sleep(30ms)
"placed {quantity} x {item} on the bench"
}
/// Scrap an item for good. A person approves every call.
guarded tool fn scrap(item: string, reason: string): string => "scrapped {item} ({reason})"
/// Breaks a goal into steps for the robots. Never acts itself.
agent Planner {
system: "Plan for two robots: Wheels drives and counts, Hands picks and scraps. Short steps."
}
/// The rover. Drives between zones and counts stock.
agent Rover {
system: "You are the rover. Use your tools, then report in one line."
tools: [drive, stock]
on toolCall(name, input) => print(" rover {name} {input}")
}
/// The arm. Picks and scraps items on the bench.
agent Arm {
system: "You are the arm. Use your tools, then report in one line."
tools: [pick, scrap]
on toolCall(name, input) => print(" arm {name} {input}")
}
fn worker(crew: Crew): string => match crew { Wheels => "rover", Hands => "arm" }
fn main() {
let plan: Plan = Planner("Restock the bench with filament and get rid of the cracked spool.")
print("plan: {plan.goal}")
for i, step in plan.steps { print(" {i + 1}. {worker(step.crew)}: {step.task}") }
// The rover and the arm work in parallel; each robot does its own steps in order.
let rover = spawn run(plan.steps.filter(s => s.crew == Wheels), Rover)
let arm = spawn run(plan.steps.filter(s => s.crew == Hands), Arm)
print("rover: {await rover}")
print("arm: {await arm}")
}
fn run(steps: Step[], robot: Agent): string {
var last = "idle"
for step in steps { last = robot(step.task) }
last
} plan: filament on the bench, cracked spool gone
1. rover: drive to the Shelves and check the filament stock
2. arm: pick 2 filament spools onto the bench
3. rover: drive back to the Dock
4. arm: scrap the cracked spool
rover drive {"to":"Shelves"}
rover stock {"item":"filament"}
arm pick {"item":"filament","quantity":2}
rover drive {"to":"Dock"}
arm scrap {"item":"cracked spool","reason":"cracked"}
rover: Back home, arrived at Dock after 40s.
arm: Left the cracked spool alone: scrapping was not approved. This is the output with nobody at the keyboard: the scrap is denied, and the arm says so.
Tests live next to the code. A test "name" { … } block runs in a fresh instance
of the program under tin test, and an agent with model: "mock" (or a tape) is
tested like anything else.
tin run examples/16-tests.tin// Tests live next to the code they test.
//
// tin test examples/16-tests.tin runs every `test` block
// tin run examples/16-tests.tin runs main; the tests are still type-checked
//
// Each test runs in a fresh instance of the program. A test fails if it panics,
// and `assert` and `assertEq` are the usual ways to make it.
type Cart = { items: string[], total: int }
fn add(cart: inout Cart, item: string, price: int) {
cart.items.push(item)
cart.total += price
}
fn discount(total: int, percent: int): Result<int, string> {
if percent < 0 || percent > 100 { return Err("percent must be between 0 and 100") }
Ok(total - total * percent / 100)
}
/// The price of an item, in cents.
tool fn price(item: string): int => match item {
"tea" => 300
"cake" => 450
_ => 0
}
agent Clerk { model: "mock", tools: [price] }
test "a cart adds up" {
var cart = Cart { items: [], total: 0 }
add(&cart, "tea", 300)
add(&cart, "cake", 450)
assertEq(cart.total, 750)
assertEq(cart.items, ["tea", "cake"])
}
test "discounts are checked" {
assertEq(discount(1000, 25), Ok(750))
assertEq(discount(1000, 0), Ok(1000))
assert(discount(1000, 150).isErr(), "150% should be refused")
}
test "tasks finish before a test does" {
let slow = spawn discount(200, 50)
sleep(5ms)
assertEq(await slow, Ok(100))
}
test "an agent can be tested offline" {
// the mock model calls the tool the prompt names, with the quoted string
assertEq(Clerk("what is the price of 'cake'?"), "mock: 450")
assertEq(Clerk.turns(), 2)
}
fn main() {
var cart = Cart { items: [], total: 0 }
add(&cart, "tea", price("tea"))
print("{cart.items} cost {discount(cart.total, 10)}")
} ["tea"] cost Ok(270)