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 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 |
tin 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:
tin 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:
- 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
boolis 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:
tin 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
tin 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.
tin run task-2.tinagent 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
tin run task-2.solution.tinagent 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