TOADAgents as data. Compiled to types.

Write an AI agent as a tiny, declarative .agent file in a token-oriented syntax derived from TOON. The toac compiler turns it into readable, fully-typed TypeScript that runs on Claude — 30–38% fewer tokens than the JSON it replaces.

🪙

Token-efficient

An agent is 30–38% fewer tokens than the equivalent JSON-schema + SDK boilerplate it replaces — cheaper to write, read, and generate. Measured, not guessed.

See the benchmarks

📐

Schema-explicit

[N] lengths and {field} headers hand a model the structure up front, so LLMs can author agents reliably.

The .agent format

🧷

Typed end-to-end

inputs, outputs, and tools become real TypeScript types backed by zod schemas. Misuse is a compile error, not a runtime surprise.

See it in the tutorial

🔧

Logic in plain TS

Tool bodies live in a co-located .tools.ts — the escape hatch for anything the declarative layer shouldn't do.

Runtime reference

🧬

Built on real TOON

Structural parsing is delegated to the spec-conformant @toon-format/toon decoder. No bespoke parser — .agent is a strict TOON superset.

Ecosystem

⚙️

Compile-first

The output is readable TypeScript you can read, diff, and debug — not an opaque runtime. The emitted code is the docs.

Browse compiled examples

The whole idea, in one screen

You describe what the agent is; the compiler writes how it works.

researcher.agentresearcher.ts (generated)

agent

agent: researcher
model: claude-opus-4-7
description: Research a topic and return a sourced summary.
inputs[1]{name,type}:
  topic,string
tools[2]: web_search,fetch_page
prompt: |
  You are a research analyst. Research: {inputs.topic}
  Use web_search to find sources, then fetch_page to read them.
  Return a cited summary.
outputs[2]{name,type}:
  summary,string
  sources,string[]

// Generated by toac from researcher.agent — do not edit.
import { createAgent, type Agent } from "toad-runtime";
import { z } from "zod";
import { web_search, fetch_page } from "./researcher.tools";

export interface ResearcherInput {
  topic: string;
}

export interface ResearcherOutput {
  summary: string;
  sources: string[];
}

const inputSchema = z.object({
  topic: z.string(),
});

const outputSchema = z.object({
  summary: z.string(),
  sources: z.array(z.string()),
});

export const researcher: Agent<ResearcherInput, ResearcherOutput> = createAgent({
  name: "researcher",
  model: "claude-opus-4-7",
  description: "Research a topic and return a sourced summary.",
  tools: { web_search, fetch_page },
  inputSchema,
  outputSchema,
  prompt: (inputs: ResearcherInput) =>
    `You are a research analyst. Research: ${inputs.topic}
Use web_search to find sources, then fetch_page to read them.
Return a cited summary.`,
});

export default researcher;

That .agent file is 101 tokens; the same agent written as JSON is 162 tokens — and at runtime, toolResultFormat: "auto" feeds tabular tool results back to the model as TOON when it's cheaper, saving another 30–40% per result.

Install

bash

# the compiler + `toac` CLI
npm i -g toad-compiler

# the runtime your compiled agents import
npm i toad-runtime @anthropic-ai/sdk

bash

toac build researcher.agent   # → researcher.ts

It's open source — come build it

TOAD is MIT-licensed and early. Star it, file an issue, or send a PR — the compiler, runtime, language features, and docs are all fair game.