Tin

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 toNeeds
"mock"the built-in offline stand-innothing
"claude-opus-5-5" and other Claude namesthe Anthropic APIANTHROPIC_API_KEY
"openai:gpt-5.1", any "openai:<model>"OpenAI Chat Completions, or any OpenAI-compatible server set by OPENAI_BASE_URLOPENAI_API_KEY (a local server needs none)
"openai-responses:gpt-5.1"the OpenAI Responses APIOPENAI_API_KEY
"gemini:gemini-3-pro", any "gemini:<model>"the Gemini APIGEMINI_API_KEY
"mistral:mistral-large-latest"MistralMISTRAL_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 APILLAMA_API_KEY
"litellm:<model>"a LiteLLM proxy, which routes to whatever its config namesLITELLM_BASE_URL, LITELLM_API_KEY
"writer:palmyra-x5"WriterWRITER_API_KEY
"vercel:anthropic/claude-opus-5-5"the Vercel AI Gateway, which reaches many providers with one keyAI_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_REGIONAWS_BEARER_TOKEN_BEDROCK, or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
left outthe model in $TIN_MODEL, otherwise claude-opus-5-5a key, for Claude
swap.tintin run swap.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)
}
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::

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.tintin run claude.tin --replay tests/tapes/agents-05-claude.json
/// 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()}")
}
  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.

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 and The Anthropic API.

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:

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.

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:

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.tintin run budget.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")
}
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.

Checking needs JavaScript; the solution below works without it.

Solution
task-1.solution.tintin run task-1.solution.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"))
}
(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.tintin run task-2.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)
}
3

Checking needs JavaScript; the solution below works without it.

Solution
task-2.solution.tintin run task-2.solution.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)
}
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 · The mock model · Agents and their settings