<!-- Real models · Tin · https://tin.ad/docs/learn/real-models/ · generated from the built page -->

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

# Real models

**Goal.** Switch from the mock to a real model by changing one line, and keep spending in check.

Every agent in this tutorial has used `model: "mock"` so that it runs anywhere. Moving to a real
model is a one-line change.

## Choosing a model

| `model:` | Goes to | Needs |
| --- | --- | --- |
| `"mock"` | the built-in offline stand-in | nothing |
| `"claude-opus-5-5"` and other Claude names | the Anthropic API | `ANTHROPIC_API_KEY` |
| `"openai:gpt-5.1"`, any `"openai:<model>"` | OpenAI Chat Completions, or any OpenAI-compatible server set by `OPENAI_BASE_URL` | `OPENAI_API_KEY` (a local server needs none) |
| `"openai-responses:gpt-5.1"` | the OpenAI Responses API | `OPENAI_API_KEY` |
| `"gemini:gemini-3-pro"`, any `"gemini:<model>"` | the Gemini API | `GEMINI_API_KEY` |
| `"mistral:mistral-large-latest"` | Mistral | `MISTRAL_API_KEY` |
| `"ollama:llama3.2:3b"`, any `"ollama:<model>"` | Ollama on your machine (or `OLLAMA_HOST`) | nothing; `ollama pull` the model first |
| `"llamacpp:qwen3-8b"` | llama.cpp's `llama-server` on your machine (or `LLAMACPP_BASE_URL`) | nothing; start it with `--jinja` for tools |
| `"llamaapi:<model>"` | Meta's Llama API | `LLAMA_API_KEY` |
| `"litellm:<model>"` | a LiteLLM proxy, which routes to whatever its config names | `LITELLM_BASE_URL`, `LITELLM_API_KEY` |
| `"writer:palmyra-x5"` | Writer | `WRITER_API_KEY` |
| `"vercel:anthropic/claude-opus-5-5"` | the Vercel AI Gateway, which reaches many providers with one key | `AI_GATEWAY_API_KEY` |
| `"bedrock:us.anthropic.claude-haiku-4-5-20251001-v1:0"` | Amazon Bedrock, with a model id or inference profile id; the region comes from `AWS_REGION` | `AWS_BEARER_TOKEN_BEDROCK`, or `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` |
| left out | the model in `$TIN_MODEL`, otherwise `claude-opus-5-5` | a key, for Claude |

*swap.tin · tin run swap.tin*

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

agent Calculator {
  model: "mock"            // swap for "claude-opus-5-5" when you have a key; nothing else changes
  system: "Use the tools for all arithmetic. Reply with just the number."
  tools: [add]
}

fn main() {
  let n: int = Calculator("add 2 and 40")
  print(n)
}
```

<!-- output -->
```text
42
```

Change `"mock"` to `"claude-opus-5-5"`, set `ANTHROPIC_API_KEY`, and it runs
against Claude. The tools, the typed reply and the loop stay the same. Without a key, the call stops and tells
you to set one, or to run offline.

The same goes for anything that speaks the OpenAI API. To use a model served on your own machine by vLLM,
LM Studio or llama.cpp, point Tin at it and name the model after `openai:`:

```tin
OPENAI_BASE_URL=http://localhost:8000/v1 tin run main.tin     # with model: "openai:Qwen/Qwen3-8B"
```

 One agent can use several models. `"openai:gpt-5.1 | ollama:llama3.2"` tries the next model when one
fails (no key, rate limited, server down), and `"route(by: openai:gpt-5.1-mini; quick: ollama:llama3.2; deep:
anthropic:claude-opus-5-5)"` lets a small model pick which one answers each question.
`"openai:gpt-5.1 | mock"` runs offline when there is no key.

The program doesn't change when the server does. The URL, key and extra headers come from the environment
(`OPENAI_HEADERS` takes a JSON object), never from the source.

## What a real model adds

Here's a real run, replayed from its tape (chapter 23). Claude picks the tools, answers in the
`Language` shape, and streams a poem through `on text`:

*claude.tin · tin run claude.tin --replay tests/tapes/agents-05-claude.json*

```tin
/// Add two integers and return the sum.
tool fn add(a: int, b: int): int => a + b

/// Multiply two integers and return the product.
tool fn multiply(a: int, b: int): int => a * b

agent Calculator {
  system: "You are a calculator. Use the tools for all arithmetic. Reply with just the number."
  tools: [add, multiply]
  on toolCall(name, input) => print("  call {name} {input}")
}

type Language = {
  name: string
  /// The year it first appeared
  year: int
  paradigm: Paradigm
  /// One sentence on what it is known for
  knownFor: string
}

type Paradigm = | Functional | ObjectOriented | Procedural | Logic | Multi

agent Historian {
  system: "You are a historian of programming languages. Be accurate and brief."
}

fn main() {
  // tools: the model decides which to call, the loop runs them
  let answer: int = Calculator("What is (17 + 25) * 3?")
  print("(17 + 25) * 3 = {answer}")

  // typed replies: ask for a list of structs, get a list of structs
  let languages: Language[] = Historian("Name three influential programming languages from before 1975.")
  for l in languages.sortBy((a, b) => a.year < b.year) {
    print("{l.year}  {l.name.padRight(8, " ")} {l.paradigm}  — {l.knownFor}")
  }

  // streaming: text handlers fire as the reply arrives
  let poet = agent {
    system: "You write very short poems."
    on text(chunk) => write(chunk)
  }
  poet("Two lines about the metal tin.")
  print()
  print("tokens used: {Calculator.tokens() + Historian.tokens() + poet.tokens()}")
}
```

<!-- output -->
```text
  call add {"a":17,"b":25}
  call multiply {"a":42,"b":3}
(17 + 25) * 3 = 126
1957  Fortran  Procedural  — The first widely used high-level language, built for scientific and numerical computing.
1958  Lisp     Functional  — Brought in garbage collection, homoiconic code-as-data, and symbolic computation, and became central to AI research.
1972  Prolog   Logic  — The first major logic programming language, used in AI and natural language processing.
Bend it slow and hear it cry,
soft gray metal, Bronze's ally.
tokens used: 3332
```

## Tools Claude brings along

Claude also has tools that Anthropic defines. Some run on Anthropic's side: list them and the model can search the web,
fetch pages and run code without you writing a `tool fn`. Others, like Claude's memory, the model asks your program
to run; you name the `tool fn` that does it, and `std/anthropic` has the usual ones ready.

```tin
import "std/anthropic"

/// Claude's memory, kept in memory.json.
tool fn remember(input: string): Result<string, string> => anthropic.memoryAt("memory.json", input)

agent Researcher {
  model: "claude-haiku-4-5"
  serverTools: { webSearch: { maxUses: 3 }, codeExecution: {} }
  tools: [remember]
  clientTools: { memory: remember }
}
```

 `tin caps` now says this agent can reach the network and run code, because its model can, through the API.
These need a real Claude model, so this snippet has no Run button. All of them, and the rest of the Anthropic API from Tin
(token counts, files, batches), are in [Tools Anthropic defines](https://tin.ad/docs/ref/agents/#anthropic-tools)
and [The Anthropic API](https://tin.ad/docs/ref/anthropic/).

## Thinking, effort and the rest of the request

Everything else a model call can carry is an agent field too, checked when the program compiles: how much to think,
how hard to try, where to stop, which tool to use, extra headers. `A.with` changes them for one question, and
`A.lastReply()` tells you what came back:

```tin
agent Analyst {
  model: "claude-haiku-5-5"
  thinking: adaptive
  effort: high
  stop: ["END"]
  headers: { "x-team": "research" }
}

fn main() {
  print(Analyst("Which of these two contracts is riskier, and why?"))
  print(Analyst.with { effort: low }.ask("Now in one sentence."))
  let r = Analyst.lastReply()
  print("{r.stopReason}: {r.usage.input} in, {r.usage.output} out, {r.usage.cacheRead} from the cache")
}
```

 A question can carry images and documents as parts: `Analyst([text("What is in this chart?"), image(png, "image/png")])`,
and a document marked `.cited()` sends its citations back in `lastReply().citations`. A word a field
doesn't take, an option the model's API removed, or a setting this model doesn't have (a thinking budget on Haiku 5.5,
effort on Haiku 4.5) is a compile error that says what to write instead. The full list is in
[Request options](https://tin.ad/docs/ref/agents/#options).

## What the mock really does

The mock isn't a model. It's a test double that behaves in a fixed, simple way, which is why the examples in
this tutorial work:

- It calls every tool the prompt names, or the first tool if none is named, and fills the arguments from the
numbers and quoted strings in the prompt, in order.

- Given tool results, it answers `mock:` followed by them. With no tools, it repeats the prompt.
- For a typed reply it fills the shape the same way: strings from quotes, numbers in order, a
`bool` is true only when the prompt says "true".

- It counts four characters as a token, so budgets work offline.

So use it to test your program's plumbing, not the model's judgement. For that, record a real run.

## Spending limits

A real model costs money per token. `maxTokens` caps what one question may use, and
`A.tokens()` tells you what an agent has used:

*budget.tin · tin run budget.tin*

```tin
/// Look up a word in the dictionary.
tool fn define(word: string): string => "a soft, silvery metal, used to coat steel so it does not rust"

agent Lexicographer {
  model: "mock"
  tools: [define]
  maxTokens: 40          // the most one question may use, input plus output
}

fn main() {
  match Lexicographer.try("define 'tin'") {
    Ok(text) => print(text)
    Err(e) => print("stopped: {e}")
  }
  print("used {Lexicographer.tokens()} tokens")
}
```

<!-- output -->
```text
stopped: OverBudget(40)
used 77 tokens
```

The first model call always runs, and here it alone used more than the budget (the tool's schema counts as
input). So the loop didn't start a second call, and `try` returned `OverBudget` instead of
a panic.

## Tasks

### Task 1: A summary on a budget

Write `summarise(title)` using an agent with an `article` tool and a
`maxTokens` of 30. Return a friendly message when the budget runs out, and a different one for
other failures.

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

**Solution

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

```tin
/// Fetch an article's text by title.
tool fn article(title: string): string => "tin ".repeat(200)

agent Summariser {
  model: "mock"
  tools: [article]
  maxTokens: 30
}

fn summarise(title: string): string {
  match Summariser.try("summarise the article '{title}'") {
    Ok(s) => s
    Err(OverBudget(n)) => "(too long to summarise within {n} tokens)"
    Err(e) => "(failed: {e})"
  }
}

fn main() {
  print(summarise("Tin"))
}
```

<!-- output -->
```text
(too long to summarise within 30 tokens)
```

`Err(OverBudget(n))` matches inside a match: a pattern within a pattern. The
catch-all `Err(e)` after it covers the other `AgentError` cases.

### Task 2: Outsmart the mock

This program prints `3`, not `7`. Why? Change only the prompt so the mock answers 7.

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

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

fn main() {
  let pets: int = Counter("I have 3 cats and 4 dogs. How many pets in total?")
  print(pets)
}
```

<!-- output -->
```text
3
```

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

**Solution

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

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

fn main() {
  // The mock fills an int with the first number in the prompt, so put the answer first.
  // A real model would add 3 + 4 by itself: this tests your code, not the model.
  let pets: int = Counter("7 pets: I have 3 cats and 4 dogs. How many pets in total?")
  print(pets)
}
```

<!-- output -->
```text
7
```

The mock fills an `int` with the first number in the prompt. A real model would do the
sum. That's the point of the task: the mock tests your program's plumbing, not how well a model reasons.

## Recap

- `model: "provider:name"` picks a real model.
- Nothing else in the program changes.
- `maxTokens` caps what one question may spend, and the program decides what to say when it runs out.

In the reference: [Models](https://tin.ad/docs/ref/agents/#models) · [The mock model](https://tin.ad/docs/ref/agents/#mock) · [Agents and their settings](https://tin.ad/docs/ref/agents/#agents)
