<!-- Typed replies · Tin · https://tin.ad/docs/learn/typed-replies/ · generated from the built page -->

[Learn](https://tin.ad/docs/learn/) · Agents · 17 of 34

# Typed replies

**Goal.** Ask an agent for a struct and get a checked struct back.

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.tin · tin run order.tin*

```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"
  })
}
```

<!-- output -->
```text
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.tin · tin run small.tin*

```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)
}
```

<!-- output -->
```text
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.tin · tin check float.tin*

```tin
agent Judge { model: "mock" }

fn main() {
  let score: float = Judge("rate this from 0 to 1")
}
```

<!-- compiler output -->
```text
error: a typed agent reply cannot be a bare float, i64, Duration, Frequency or Angle; 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.tin · tin run wrapped.tin*

```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)
}
```

<!-- output -->
```text
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.tin · tin run try.tin*

```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}")
  }
}
```

<!-- output -->
```text
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.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-1.solution.tin · tin run task-1.solution.tin*

```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")
}
```

<!-- output -->
```text
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"?

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-2.solution.tin · tin run task-2.solution.tin*

```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))
}
```

<!-- output -->
```text
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.

## Recap

- Give the call a type, and the reply is decoded into it.
- Any place a type is known works: `let`, parameters, fields.
- A reply that does not fit is an error you handle, not a crash.

In the reference: [Typed replies](https://tin.ad/docs/ref/agents/#typed) · [When an agent call fails](https://tin.ad/docs/ref/agents/#failures)
