Learn Tin · Part 3: Real programs · Chapter 26
A fleet of agents
A larger program, read piece by piece.
This chapter reads one larger program, piece by piece: a planner and two robots that restock a workbench. It uses most of Part 2, and shows how those features fit together. The whole file is at the end, with its real output.
1. The plan is a type
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[]
} The planner won't answer in prose. It answers with a Plan (chapter 17), so the rest of the program
works with real values. The /// comments go into the schema the model sees. Because
Crew has only two cases, the model can't invent a third robot.
2. Each robot's tools
/// 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})" Ordinary functions, marked tool (chapter 16). Scrapping can't be undone, so it's
guarded: a person approves each call (chapter 18).
3. Three agents, each with only its own tools
/// 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}")
} The planner has no tools at all, so it can only plan. The rover can't scrap anything, because it was never
given scrap. The compiler's capability report (chapter 19) confirms this:
tin caps fleet.tinagent Planner
tools: none
can call freely: nothing
needs approval: nothing
capabilities: model
agent Rover
tools: drive, stock
can call freely: drive, stock
needs approval: nothing
capabilities: model, clock, output
agent Arm
tools: pick, scrap (guarded)
can call freely: pick
needs approval: scrap
capabilities: model, clock, output
tools
drive free clock
stock free pure
pick free clock
scrap guarded pure 4. Plan, check, then act in parallel
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
} The plan is printed before anything moves, so you can check it first (see task 1). Then each robot gets its own
steps, and the two run at the same time with spawn (chapter 21). Each robot's steps still run in
order. run takes any Agent, so the same loop drives both.
The whole program
This run replays a recorded session (chapter 23), and --yes approves the scrap:
tin run fleet.tin --replay tests/tapes/agents-08-fleet.json --yestype 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: Done: scrapped cracked spool (cracked). Tasks
●●○ Task 1: Check the plan
Before dispatching, a plan should be checked. Write check(plan): Result<Plan, string> that
refuses an empty plan, or one with more than five steps. Prove it with tests. You don't need a model for this:
a Plan is just a value.
Solution
tin test task-1.solution.tintype Crew = | Wheels | Hands
type Step = { crew: Crew, task: string }
type Plan = { goal: string, steps: Step[] }
/// Checks a plan before anything moves.
fn check(plan: Plan): Result<Plan, string> {
if plan.steps.len == 0 { return Err("the plan has no steps") }
if plan.steps.len > 5 { return Err("{plan.steps.len} steps is too many; at most 5") }
Ok(plan)
}
test "a short plan passes" {
let p = Plan { goal: "tidy", steps: [Step { crew: Wheels, task: "drive to the dock" }] }
assert(check(p).isOk())
}
test "an empty plan is refused" {
assertEq(check(Plan { goal: "nothing", steps: [] }), Err("the plan has no steps"))
}
test "a long plan is refused" {
let step = Step { crew: Hands, task: "pick" }
assertEq(check(Plan { goal: "busy", steps: [step, step, step, step, step, step] }), Err("6 steps is too many; at most 5"))
} ✔ a short plan passes
✔ an empty plan is refused
✔ a long plan is refused
3 passed, 0 failed ●○○ Task 2: Who can scrap?
Which agents and functions can reach scrap? Ask the compiler.
Solution
tin caps task-2.solution.tin --reach scraptype 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
} agents that can reach scrap: Arm
functions that can reach scrap: main main appears because it calls Arm, whose loop can call
scrap. A person still approves every one of those calls.
What's next
Next: A command-line tool. tin new, input, formatting and building a .wasm.
In the reference: Typed replies · Guarded tools · Concurrency