Sn Tin

Learn Tin · Part 2: Agents · Chapter 24

Real models

Swap the mock for a real model. Nothing else changes.

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

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.

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
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.

What's next

Next: Calling JavaScript. import js and extern fn, checked at the boundary.

In the reference: Models · The mock model · Agents and their settings