Sn Tin

Learn Tin · Part 2: Agents · Chapter 16

Tools

Give an agent functions to call. Their schemas come from your types.

A tool is a function

Write tool fn instead of fn and list the function in an agent's tools. Now the model can call it. It's still an ordinary function, so you can call it yourself too.

first-tool.tintin run first-tool.tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

agent Calculator {
  model: "mock"
  system: "Use the tools for every calculation."
  tools: [add]
}

fn main() {
  print(add(2, 3))                       // a tool fn is still an ordinary function
  print(Calculator("please add 19 and 23"))
}
5
mock: 42

The mock calls every tool your prompt mentions by name, and fills the arguments from the numbers in the prompt, in order. A real model reads the descriptions and decides for itself.

The agent loop

When an agent has tools, one call runs a loop: ask the model, run the tools it asks for, send back the results, ask again, until the model answers with text. on toolCall and on toolResult let you watch each step:

events.tintin run events.tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

/// Multiply two integers.
tool fn times(a: int, b: int): int => a * b

agent Calculator {
  model: "mock"
  tools: [add, times]

  // handlers run while the agent loop runs
  on toolCall(name, input) => print("  call   {name} {input}")
  on toolResult(name, output, ok) => print("  result {name}: {output}")
}

fn main() {
  print(Calculator("times 6 and 7"))
}
  call   times {"a":6,"b":7}
  result times: 42
mock: 42

If the model asks for several tools in one reply, they run at the same time.

Schemas come from your types

A model needs to know each tool's name, what it does, and the shape of its arguments as a JSON Schema. In Tin, you never write that schema. The compiler derives it from the signature, and the /// comments become descriptions. tin tools shows what the model will see:

schema.tintin tools schema.tin
type Unit = | Celsius | Fahrenheit

/// Look up the weather for a city.
tool fn weather(
  /// City name, for example "Istanbul"
  city: string,
  unit: Unit,
  /// How many days ahead (0 = today). Optional.
  days: Option<int>,
): string => "sunny in {city}"

fn main() {}
[
  {
    "name": "weather",
    "description": "Look up the weather for a city.",
    "schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name, for example \"Istanbul\""
        },
        "unit": {
          "type": "string",
          "enum": [
            "Celsius",
            "Fahrenheit"
          ]
        },
        "days": {
          "type": "integer",
          "description": "How many days ahead (0 = today). Optional."
        }
      },
      "required": [
        "city",
        "unit"
      ],
      "additionalProperties": false
    }
  }
]

Look at what came from where:

Before a tool runs, its arguments are checked against the schema. If the model sends the wrong shape, the tool doesn't run. The model gets told which argument was wrong.

When a tool fails

Return a Result for failures you expect. An Err isn't a crash: it goes back to the model as a failed call, and the model decides what to do next.

failing-tool.tintin run failing-tool.tin
/// Divide one integer by another.
tool fn divide(a: int, b: int): Result<int, string> {
  if b == 0 { return Err("cannot divide by zero") }
  Ok(a / b)
}

agent Calculator {
  model: "mock"
  tools: [divide]
  on toolResult(name, output, ok) => print("  {if ok { "ok" } else { "failed" }} {name}: {output}")
}

fn main() {
  print(Calculator("divide 10 by 2"))
  print(Calculator("divide 10 by 0"))      // an Err goes back to the model; the program keeps going
}
  ok divide: 5
mock: 5
  failed divide: cannot divide by zero
mock: error: cannot divide by zero

A panic inside a tool, such as dividing by zero, is handled the same way: the model sees a failed call, and your program keeps running.

What a tool can take

Tool parameters and results must be plain data: numbers, bool, string, Duration, arrays, structs, sum types and Option. A function can't be sent to a model:

not-data.tintin check not-data.tin
/// Run a function twice.
tool fn twice(f: (int) => int, x: int): int => f(f(x))

fn main() {}
error: a (int) => int cannot cross the agent boundary — tool parameters, tool results and typed agent replies must be plain data
 --> not-data.tin:2:15
  |
2 | tool fn twice(f: (int) => int, x: int): int => f(f(x))
  |               ^^^^^^^^^^^^^^^

And a tool can't be generic, because a model needs one concrete schema:

generic.tintin check generic.tin
/// The first item.
tool fn firstOf<T>(xs: T[]): T => xs[0]

fn main() {}
error: a tool fn cannot be generic: the model needs one concrete schema
 --> generic.tin:2:1
  |
2 | tool fn firstOf<T>(xs: T[]): T => xs[0]
  | ^^^^^^^^^^^^^^^

Tasks

●○○ Task 1: Another tool

Give the calculator a subtract tool, then ask it to "subtract 10 and 3" and print each call.

Solution
task-1.solution.tintin run task-1.solution.tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

/// Subtract b from a.
tool fn subtract(a: int, b: int): int => a - b

agent Calculator {
  model: "mock"
  tools: [add, subtract]
  on toolCall(name, input) => print("  call {name} {input}")
}

fn main() {
  print(Calculator("subtract 10 and 3"))
}
  call subtract {"a":10,"b":3}
mock: 7

●●○ Task 2: Design a schema

Write a tool addTodo with a title, a priority (Low, Normal or Urgent) and an optional due date, so that the model can't send a priority you don't support. Check the schema with tin tools.

Solution
task-2.solution.tintin tools task-2.solution.tin
type Priority = | Low | Normal | Urgent

/// Add a todo item.
tool fn addTodo(
  /// What needs doing
  title: string,
  priority: Priority,
  /// Optional due date, as YYYY-MM-DD
  due: Option<string>,
): string => "added {title}"

fn main() {}
[
  {
    "name": "addTodo",
    "description": "Add a todo item.",
    "schema": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "What needs doing"
        },
        "priority": {
          "type": "string",
          "enum": [
            "Low",
            "Normal",
            "Urgent"
          ]
        },
        "due": {
          "type": "string",
          "description": "Optional due date, as YYYY-MM-DD"
        }
      },
      "required": [
        "title",
        "priority"
      ],
      "additionalProperties": false
    }
  }
]

What's next

Next: Typed replies. Ask for a struct and get a struct back, not text to parse.

In the reference: Tools · What the model sees back · How types become schemas