Sn Tin

Learn Tin · Part 2: Agents · Chapter 21

spawn, await and within

Run agents at the same time, cancel them, and give them a time budget.

Agents are slow: a model call takes seconds. If you ask three agents one after another, you wait three times. Tin lets you run them at the same time, and makes sure nothing is left running when you're done.

spawn and await

spawn f(x) starts the call as a task and gives you a Task<T> straight away. await waits for its result.

spawn.tintin run spawn.tin
fn fetchScore(name: string, delay: Duration): int {
  sleep(delay)                 // stands in for a slow network call
  name.len * 10
}

fn main() {
  let a = spawn fetchScore("ada", 1s)      // starts now, returns a Task<int>
  let b = spawn fetchScore("grace", 1s)
  print(await a + await b)                   // wait for both results
}
80

Each call waits a second, but the program takes about one second, not two, because both waits overlap. Try it with time tin run spawn.tin. You don't mark functions async: any function may pause, and its callers don't need to know.

Agents at the same time

One agent holds one conversation, so calls to the same agent wait their turn. fresh() gives each task its own copy, and those run side by side:

agents.tintin run agents.tin
/// Look up the population of a city, in millions.
tool fn population(city: string): int => match city {
  "Istanbul" => 16
  "Tokyo" => 14
  _ => 1
}

agent Researcher { model: "mock", tools: [population] }

fn main() {
  // fresh() gives each task its own conversation, so they can run at the same time
  let tasks = ["Istanbul", "Tokyo", "Lima"].map(c => spawn Researcher.fresh().ask("population of '{c}'"))
  for t in tasks { print(await t) }
}
mock: 16
mock: 14
mock: 1

Time limits: within

task |> within(limit) waits at most limit. You get Some(result) if the task finished in time. Otherwise the task is stopped and you get None.

within.tintin run within.tin
fn crunch(label: string, cost: Duration): string {
  sleep(cost)
  "{label} done"
}

fn main() {
  print(spawn crunch("quick", 5ms) |> within(1s))       // Some(...): finished in time
  print(spawn crunch("endless", 1h) |> within(20ms))    // None: stopped after 20ms
}
Some("quick done")
None

That's a latency budget for an agent: if the model is slow, fall back to something else.

budget.tintin run budget.tin
agent Fast { model: "mock" }

fn main() {
  // give an agent call a time budget; the answer is an Option
  match spawn Fast.ask("summarise this") |> within(2s) {
    Some(text) => print(text)
    None => print("too slow, using the cached summary")
  }
}
mock: summarise this

When the limit passes, the agent's task is stopped properly: a reply that arrives late is dropped, and the tool calls it asked for never run.

Stopping a task

t.stop() stops a task and everything it started. The task ends at its next pause, such as a sleep, an await, a fetch or an agent call, and nothing after that runs.

stop.tintin run stop.tin
fn job(): string {
  print("job started")
  sleep(1h)                 // a long wait: the task pauses here
  print("never printed")
  "done"
}

fn main() {
  let t = spawn job()
  sleep(10ms)
  t.stop()                  // stops the task (and anything it started) at its pause
  print("stopped it")
}
job started
stopped it

A task can't outlive the task that started it. await t returns only when t and everything it spawned have finished, so a program never quietly leaves work running in the background.

A trap: what spawn takes

spawn takes everything written after it, so spawn work().stop() means "spawn work().stop()". The compiler notices:

precedence.tintin check precedence.tin
fn work(): int => 1

fn main() {
  spawn work().stop()
}
error: no method 'stop' for int
 --> precedence.tin:4:9
  |
4 |   spawn work().stop()
  |         ^^^^^^^^^^^
  = note: `spawn` takes everything after it, so this method is being called on the result of the call, not on the task
  = note: keep the task first: `let t = spawn f()`, then `t.stop()`

Put the task in a variable first, as in Stopping a task, or use |>.

Tasks

●○○ Task 1: Fan out

slowDouble(x) sleeps 20ms and returns x * 2. Run it for 1, 2, 3 and 4 at the same time and print the sum.

Solution
task-1.solution.tintin run task-1.solution.tin
fn slowDouble(x: int): int {
  sleep(20ms)
  x * 2
}

fn main() {
  let tasks = [1, 2, 3, 4].map(x => spawn slowDouble(x))
  var total = 0
  for t in tasks { total += await t }
  print(total)
}
20

●●○ Task 2: A fallback

Write ask(q): give the Primary agent one second, and if it doesn't answer in time, ask Backup instead.

Solution
task-2.solution.tintin run task-2.solution.tin
agent Primary { model: "mock" }
agent Backup { model: "mock", system: "Answer briefly." }

fn ask(q: string): string {
  match spawn Primary.ask(q) |> within(1s) {
    Some(a) => a
    None => Backup(q)
  }
}

fn main() {
  print(ask("what is tin?"))
}
mock: what is tin?

What's next

Next: Code as action. An agent that answers with a small, checked Tin program.

In the reference: Concurrency · Sub-agents and concurrency