Learn Tin · Part 2: Agents · Chapter 17
Typed replies
Ask for a struct and get a struct back, not text to parse.
Most agent code spends its effort turning a model's text back into data: "reply in JSON", parse it, check it, ask again when it's wrong. In Tin you say which type you want, and you get a value of that type.
Ask for a struct, get a struct
tin run order.tintype Size = | Small | Medium | Large
type Order = {
/// What the customer wants to drink
drink: string
size: Size
/// How many cups
quantity: int
/// Extra requests, if any
notes: Option<string>
}
agent Clerk { model: "mock", system: "You take coffee orders." }
fn main() {
let order: Order = Clerk("Two cups please: 2 of the 'oat latte', Large")
print(order)
print("{order.quantity} x {order.drink}")
print(match order.size {
Large => "use the big cups"
_ => "regular cups"
})
} Order { drink: "oat latte", size: Large, quantity: 2, notes: None }
2 x oat latte
use the big cups Nothing here parses text. Because order is declared as an Order, the compiler
generates Order's schema, the same way it does for tool parameters, and the runtime makes the model
answer in that shape. size is a real Size you can match on, and
notes is a real Option.
How it works: the runtime gives the model one extra tool, answer, whose parameters
are the expected type, and tells it to finish by calling it. If the answer doesn't fit, the model is told what
was wrong and tries again.
Wherever a type is known
The expected type can come from a let, a return type, a parameter, or an if
condition, which asks for a bool. With no expected type, or string, you get the
model's text.
tin run small.tinagent Judge { model: "mock" }
fn legs(animal: string): int => Judge("how many legs does a {animal} have? 8")
fn main() {
print(legs("spider") * 2) // the return type asks for an int
if Judge("is 'hello' a greeting? true") { // an if condition asks for a bool
print("yes, a greeting")
}
let word: string = Judge("one word for 'happy'") // string: the model's text, as usual
print(word)
} 16
yes, a greeting
mock: one word for 'happy' Numbers with a meaning
A bare float isn't allowed as a reply. A number like 0.8 means little without saying what it
measures, so the compiler asks you to name it:
tin check float.tinagent Judge { model: "mock" }
fn main() {
let score: float = Judge("rate this from 0 to 1")
} error: a typed agent reply cannot be a bare float, i64, Duration or Frequency; wrap it in a type: `type Answer = { value: float }`
--> float.tin:4:22
|
4 | let score: float = Judge("rate this from 0 to 1")
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Wrapping it in a struct gives you a place to describe it, and the model sees that description:
tin run wrapped.tintype Score = {
/// From 0.0 (bad) to 1.0 (great)
value: float
}
agent Judge { model: "mock" }
fn main() {
let s: Score = Judge("how good is this draft? 0.8")
print(s.value)
} 0.8 When the call fails
A plain agent call either answers or stops the program with a panic, for example when it runs out of turns.
A.try(...) makes the same call but returns a Result, so you can retry, fall back or
explain. The error is an AgentError, a sum type: TurnLimit, OverBudget,
Refused, NoAnswer and others.
tin run try.tin/// Add two integers.
tool fn add(a: int, b: int): int => a + b
agent Hasty { model: "mock", tools: [add], maxTurns: 1 } // only one model call allowed
fn main() {
// A.try gives a Result instead of stopping the program when the call fails
match Hasty.try("add 2 and 3") {
Ok(text) => print(text)
Err(e) => print("no answer: {e}")
}
} no answer: TurnLimit(1) Tasks
●●○ Task 1: Read an invitation
Define an Event with a title, a date, a host and a number of guests. Ask an agent to read it out
of a message, then print the fields.
Solution
tin run task-1.solution.tintype Event = {
title: string
/// The day, as YYYY-MM-DD
date: string
/// Who organises it
host: string
/// How many people come
guests: int
}
agent Reader { model: "mock", system: "Extract calendar events from messages." }
fn main() {
let e: Event = Reader("6 people for 'Team lunch' on '2026-12-01', 'Ada' is hosting")
print("{e.title} on {e.date}, hosted by {e.host}, {e.guests} guests")
} Team lunch on 2026-12-01, hosted by Ada, 6 guests ●●○ Task 2: Route by mood
Ask an agent for a Mood (Happy, Neutral or Upset), then
pick a reply with match. Which part of your program would need to change if the model could answer
"furious"?
Solution
tin run task-2.solution.tintype Mood = | Happy | Neutral | Upset
agent Reader { model: "mock" }
fn reply(m: Mood): string => match m {
Happy => "Glad to hear it!"
Neutral => "Thanks for the note."
Upset => "Sorry about that. A person will call you."
}
fn main() {
let mood: Mood = Reader("how does this customer feel? 'Upset'")
print(reply(mood))
} Sorry about that. A person will call you. None: the model can't answer "furious". The schema only allows the three variants, and an answer outside it is sent back to the model as wrong.
What's next
Next: Guarded tools and approval. A person approves every call to a dangerous tool.
In the reference: Typed replies · When an agent call fails