Sn Tin

Learn Tin · Part 2: Agents · Chapter 15

Your first agent

An agent block, called like a function.

Part 1 was an ordinary language. Part 2 is the reason Tin exists: agents are part of the language, not a library. The compiler knows about them, checks them, and builds the loop that runs them.

Hello, agent

An agent block names a model and a system prompt. You call an agent like a function: a string in, a string out.

hello.tintin run hello.tin
agent Echo {
  model: "mock"
  system: "You repeat what you are told."
}

fn main() {
  let answer = Echo("hello, agent")    // an agent is called like a function
  print(answer)
}
mock: hello, agent

The mock model

Every example in this tutorial uses model: "mock". It's built into Tin, never touches the network and needs no key, so the examples run anywhere, give the same answer every time, and are checked when this site is built.

The mock is a test double, not a model. With no tools it just answers mock: plus your prompt. That's enough to learn how agents work. Chapter 24 swaps in a real model, and nothing else in the program changes.

Agents remember

An agent keeps its conversation. Each call adds to the history the model sees, and reset() starts over. The mock doesn't use that history, so the output below can't show it, but a real model would answer the second question with "Ada".

memory.tintin run memory.tin
agent Echo { model: "mock" }

fn main() {
  print(Echo("my name is Ada"))
  print(Echo("what is my name?"))    // a real model would see both messages and answer "Ada"
  print("model calls so far: {Echo.turns()}")
  Echo.reset()                        // forget the conversation: the next call starts fresh
  print(Echo("what is my name?"))
}
mock: my name is Ada
mock: what is my name?
model calls so far: 2
mock: what is my name?

turns() counts model calls, and tokens() counts tokens used. Neither is cleared by reset().

Agents are values

An agent written at the top level exists once, for the whole program. Written as an expression, agent { ... } makes a new agent each time, and it can use local values. Agents have the type Agent, so you can return them, pass them around and keep them in arrays.

local.tintin run local.tin
fn greeter(style: string): Agent {
  // written as an expression, `agent { ... }` makes a new agent each time
  agent {
    model: "mock"
    system: "Answer like a {style}."
  }
}

fn main() {
  let pirate = greeter("pirate")
  let poet = greeter("poet")
  print(pirate("ahoy"))
  print(poet("good morning"))
}
mock: ahoy
mock: good morning

Watching the loop

tin run --trace prints each step of the agent loop. Here there's only one step, but once agents have tools (next chapter) the trace shows every call.

trace.tintin run trace.tin --trace
agent Echo { model: "mock" }

fn main() {
  print(Echo("show me the loop"))
}
[Echo] turn 1 → mock
mock: show me the loop

A first look at typed replies

Here's a taste of chapter 17. If you ask for an int, the model is asked for an int, the answer is checked, and you get an int back. No string to parse:

typed.tintin run typed.tin
agent Counter { model: "mock" }

fn main() {
  // Ask for an int, get an int. Chapter 17 is about this.
  let n: int = Counter("how many legs does a spider have? 8")
  print(n + 1)
}
9

Tasks

●○○ Task 1: A helper

Declare an agent Helper with a system prompt of your own, ask it two questions in a loop, and print how many model calls it made.

Solution
task-1.solution.tintin run task-1.solution.tin
agent Helper {
  model: "mock"
  system: "You are a friendly helper. Keep answers short."
}

fn main() {
  for q in ["hi", "what can you do?"] {
    print(Helper(q))
  }
  print("turns: {Helper.turns()}")
}
mock: hi
mock: what can you do?
turns: 2

●●○ Task 2: Two conversations

Make an agent with agent { model: "mock" }, then a copy with .fresh(). Ask the first one two questions and the copy one. How many turns does each report?

Solution
task-2.solution.tintin run task-2.solution.tin
fn main() {
  let a = agent { model: "mock" }
  let b = a.fresh()       // a copy with an empty conversation
  print(a("one"))
  print(a("two"))
  print(b("three"))
  print("a: {a.turns()}, b: {b.turns()}")
}
mock: one
mock: two
mock: three
a: 2, b: 1

What's next

Next: Tools. Give an agent functions to call. Their schemas come from your types.

In the reference: Agents · The mock model