Running and deploying

You have written an agent and run it offline. This lesson covers the three ways to drive it, how to point it at a real model, how to bound an unattended run, and how to run agents that wake on a schedule or a file change.

Three ways to run

The orch runcommand drives an agent in one of three modes. With no flags it opens an interactive chat against the agent’s on message handler. With -t it runs a single task and prints the result. With --skill it calls one named skill with typed arguments.

# interactive chat
orch run assistant.orch

# one-shot task
orch run assistant.orch -t "Summarize today's incidents"

# call a named skill with arguments
orch run triage.orch --skill classify report="disk is full on db-1"

Use orch check while you edit and orch fmt to keep the file in canonical style. Both are covered in the CLI reference.

From the mock provider to a real model

Every example so far used model { provider: mock, name: "echo" }, which runs with no network and no key. To talk to a real model, change the model block. Nothing else in the program changes.

agent Assistant {
    model {
        provider: anthropic
        name: "claude-opus-4-8"
        temperature: 0.4
        max_tokens: 2048
        api_key: env("ANTHROPIC_API_KEY")
        fallback: { provider: ollama, name: "llama3.1" }
    }

    on message(text: str) -> str {
        return gen "Answer clearly: {text}"
    }
}

The supported providers are anthropic, openai, ollama, groq, together, openrouter, and mock. The fallback chain is used when the primary provider fails. Keys come from the environment, so they never live in the source file.

Bounding an unattended run

An agent that runs without a person watching needs a ceiling. Set one in the policy block, or open a tighter scope with budget around the work. A budget can only tighten an outer limit, never loosen it.

agent Nightly {
    model { provider: anthropic, name: "claude-sonnet-4-6" }
    policy { max_steps: 12, max_tool_calls: 30, max_spend: $2.00, allow_shell: "never" }

    on schedule(every: 1h) {
        budget(spend: $0.25, steps: 6) {
            delegate "Check the status page and summarize anything new"
        }
    }
}

When you run triggers unattended, Orchard also applies a default spend cap of $5.00 per run as a backstop. See the policy lesson for the full envelope and its defaults.

Schedule and file triggers

Handlers named on schedule and on file let an agent wake on its own. orch serve runs the file as a long-lived process and fires those handlers.

on schedule(every: 1h) {
    delegate "Post a one-line summary of new error logs"
}

on file(path: str) in "./inbox" {
    delegate "Process the document at {path} and file the result"
}

orch serve agent.orch

In CI and in production

• Run orch check in CI so a broken agent never ships. It parses, type-checks, and lints without executing.
• Commit the IR if you want reproducible runs: orch compile -o agent.ir.json. The interpreter runs the IR, so a compiled run and an interpreted run behave identically.
• Ship the CLI in a container with the Docker image, or embed the runtime in your own service.

Embedding in your own program

The CLI is a thin layer over a library. When you want an agent inside a Rust service, a C program, a Python application, or a browser tab, drive it through the embedding API instead of the command line. Continue with Embedding Orchard and the API reference.