Learn Orchard

This is the tutorial. It starts with an agent you can read in one breath and ends with one that runs typed generation, calls tools, keeps state, and fans work out across concurrent spans. You write each agent in a single .orch file and run it with one command.

How the tutorial works

Every example runs offline. The model block in each lesson uses model { provider: mock, name: "echo" }, which replies without a network call, an API key, or a bill. Everything around the model is real: tools actually run, state is actually committed to the store, and the autonomous loop genuinely invokes your skills. When you are ready for a real model, you swap two fields (provider and name, plus a key) and the same agent talks to a live LLM. Nothing else changes.

You will need the orch command. Install it from the install page for your platform, then confirm it works:

orch --version

Three commands carry you through the whole tutorial:

• orch run file.orch -t "your task" runs an agent against a one-shot task.
• orch check file.orch type-checks the file and reports errors with a caret pointing at the span. Run it after every edit.
• orch fmt file.orch rewrites the file into canonical form so your code looks like everyone else's.

The lessons

Work through these in order. Each one builds on the last.

1. Hello, agent: the smallest real agent: a file, a model, a handler, and one model call.
2. A tour of the language: types, literals, operators, and control flow, the ordinary parts you use everywhere.
3. Typed generation: gen as T, the feature that makes the model return a value you declared instead of prose you have to parse.
4. Tools and skills: deterministic effects, model-using procedures, and pure helpers.
5. Memory and state: typed transactional state, durable facts, and conversation history.
6. Concurrency: spawn, await, and parallel, with budgets shared safely across spans.
7. The autonomous loop and policy : delegate, the perceive-think-act loop, and the safety envelope that bounds it.
8. Running and deploying: the CLI in depth, the compiled IR, and serving an agent.

How to read this

Type the examples out rather than copying them. Run orch check after each change and read the diagnostic when it complains; the checker is precise about what it wants. The lessons introduce one idea at a time, so if a later example uses something you have not seen, it is defined in an earlier lesson. Keep a terminal open and run every snippet as you go.

This tutorial is the gentle path. When you want the exact rule for a construct, reach for the Language Reference, which is concise and complete. For every flag and subcommand of the tool, see the CLI Reference.

Next. Start with Hello, agent and have your first agent replying in a minute.