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.
tin 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:
tin 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:
tin tools schema.tintype 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:
- The sum type
Unitbecame a string limited to"Celsius"or"Fahrenheit". The model can't send anything else. - The
Option<int>parameter is left out ofrequired, so the model may skip it. Every other parameter is required. - Rename a parameter or change its type and the schema changes with it, because it's generated from the code.
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.
tin 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:
tin 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:
tin 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
tin 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
tin tools task-2.solution.tintype 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