Sn Tin

Learn Tin · Part 2: Agents · Chapter 19

Capabilities

The compiler proves what each agent can reach.

Before you let a model loose, you want to know what it can actually do. In most languages you read every tool and guess. In Tin the compiler already knows, because it has followed every call. tin caps prints it.

What each agent can reach

shop.tintin caps shop.tin
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Today's date, for the receipt.
tool fn today(): string => "{now()}"

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents}"

/// Answers questions about the menu. Read-only.
agent Menu { model: "mock", tools: [price] }

/// Takes orders and charges for them.
agent Till { model: "mock", tools: [Menu, today, charge] }

fn main() {
  print(Till("charge 'visa' 300"))
}
agent Menu
  tools:           price
  can call freely: price
  needs approval:  nothing
  capabilities:    model

agent Till
  tools:           Menu (agent), today, charge (guarded)
  can call freely: price, today
  needs approval:  charge
  capabilities:    model, clock

tools
  price   free     pure
  today   free     clock
  charge  guarded  pure

Read it from the bottom up:

Touching the outside world

The capabilities come from the built-in functions a tool can end up calling: fetch means net, env means env, print means output, now and sleep mean clock, and calling an agent means model.

fetch.tintin caps fetch.tin
/// Read a web page.
tool fn readPage(url: string): string => fetch(url).or("")

/// Read an environment variable.
tool fn setting(name: string): string => env(name)

agent Browser { model: "mock", tools: [readPage] }
agent Ops { model: "mock", tools: [setting] }

fn main() {}
agent Browser
  tools:           readPage
  can call freely: readPage
  needs approval:  nothing
  capabilities:    model, net

agent Ops
  tools:           setting
  can call freely: setting
  needs approval:  nothing
  capabilities:    model, env

tools
  readPage  free     net
  setting   free     env

Because Tin has no global variables and tool arguments are plain data, a tool can only run code its body names. That's why this report is exact rather than a best guess.

Who can reach a function?

Turn the question around with tin caps file.tin --reach charge. For this program:

reach.tintin caps reach.tin --reach charge
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents} to {card}"

agent Menu { model: "mock", tools: [price] }
agent Till {
  model: "mock"
  tools: [Menu, charge]
  on toolCall(name, input) => print("  {name} {input}")
}

fn main() {
  print(Menu("price of 'tea'"))
  print(Till("charge 'visa' 300"))
}
agents that can reach charge:    Till
functions that can reach charge: main

Only Till can, and main reaches it through Till. Menu can't, whatever its model decides.

Not yet: capabilities are worked out and reported, but you can't yet write "this agent may not use the network" and have the compiler enforce it. Today you read the report, or put it in a test.

Tasks

●○○ Task 1: Predict the report

An agent Forecaster has a tool that calls fetch, and an agent Notes has a tool that calls print. Which capabilities does tin caps list for each? Write it and check.

Solution
task-1.solution.tintin caps task-1.solution.tin
/// Read the weather for a city.
tool fn weather(city: string): string => fetch("https://example.com/weather?city={city}").or("unknown")

/// Remember a note.
tool fn note(text: string): string {
  print("note: {text}")
  "saved"
}

agent Forecaster { model: "mock", tools: [weather] }
agent Notes { model: "mock", tools: [note] }

fn main() {}
agent Forecaster
  tools:           weather
  can call freely: weather
  needs approval:  nothing
  capabilities:    model, net

agent Notes
  tools:           note
  can call freely: note
  needs approval:  nothing
  capabilities:    model, output

tools
  weather  free     net
  note     free     output

●●○ Task 2: Split the power

Change the shop so that Till can only reach charge through a separate Cashier agent. Does that change what Till needs approval for?

Solution
task-2.solution.tintin caps task-2.solution.tin
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents}"

/// Takes orders. It can no longer charge on its own: the Cashier does that.
agent Till { model: "mock", tools: [price, Cashier] }

/// Charges cards, after a person approves.
agent Cashier { model: "mock", tools: [charge] }

fn main() {}
agent Till
  tools:           price, Cashier (agent)
  can call freely: price
  needs approval:  charge
  capabilities:    model

agent Cashier
  tools:           charge (guarded)
  can call freely: nothing
  needs approval:  charge
  capabilities:    model

tools
  price   free     pure
  charge  guarded  pure

No. Till can still reach charge through Cashier, so it still appears under needs approval. Moving a tool behind a sub-agent changes who asks, not what can happen.

What's next

Next: Sub-agents and teams. Agents that call agents: planners, workers and critics.

In the reference: Capabilities · The compiler checks the approval path