<!-- Guarded tools and teams · Tin · https://tin.ad/docs/tour/teams/ · generated from the built page -->

[Tour](https://tin.ad/docs/tour/) · 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 `|>`.

*examples/agents/04-approval.tin · tin run examples/agents/04-approval.tin*

```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}")
  }
}
```

<!-- output -->
```text
  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.

*examples/agents/07-capabilities.tin · tin run examples/agents/07-capabilities.tin*

```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"))
}
```

<!-- output -->
```text
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.

*examples/agents/03-team.tin · tin run examples/agents/03-team.tin*

```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)
}
```

<!-- output -->
```text
  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`.

*examples/agents/08-fleet.tin · tin run examples/agents/08-fleet.tin --replay tests/tapes/agents-08-fleet.json*

```tin
// 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
}
```

<!-- output -->
```text
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.

*examples/16-tests.tin · tin run examples/16-tests.tin*

```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)}")
}
```

<!-- output -->
```text
["tea"] cost Ok(270)
```
