Sn Tin

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

order.tintin run order.tin
type 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.

small.tintin run small.tin
agent 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:

float.tintin check float.tin
agent 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:

wrapped.tintin run wrapped.tin
type 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.

try.tintin 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
task-1.solution.tintin run task-1.solution.tin
type 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
task-2.solution.tintin run task-2.solution.tin
type 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