<!-- Your first agent · Tin · https://tin.ad/docs/learn/first-agent/ · generated from the built page -->

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

# Your first agent

**Goal.** Declare an `agent`, call it like a function, and watch its loop with the offline mock model.

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.tin · tin run hello.tin*

```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)
}
```

<!-- output -->
```text
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.tin · tin run memory.tin*

```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?"))
}
```

<!-- output -->
```text
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.tin · tin run local.tin*

```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"))
}
```

<!-- output -->
```text
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.tin · tin run trace.tin --trace*

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

fn main() {
  print(Echo("show me the loop"))
}
```

<!-- output -->
```text
[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.tin · tin run typed.tin*

```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)
}
```

<!-- output -->
```text
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.

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

**Solution

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

```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()}")
}
```

<!-- output -->
```text
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?

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

**Solution

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

```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()}")
}
```

<!-- output -->
```text
mock: one
mock: two
mock: three
a: 2, b: 1
```

## Recap

- An agent is a declaration with a model and a prompt; calling it returns its reply.
- The `mock` model runs offline, so examples are repeatable.
- Agents keep their conversation and are ordinary values.

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