Your First Environment

The Quickstart ran an agent inside a world someone else built. This page opens that world up. You will change a fact and watch the grading follow, then add a task of your own. Both take a few minutes, and between them they explain most of how Silo works. Everything below continues from the demo environment created in the Quickstart.

Look inside

.silo/environments/demo/
├── silo.environment.json   name, template, entrypoint
├── index.ts                the three exports Silo loads
├── environment.ts          data/ → a fresh cloned world
├── state.ts                `export type State` + domain helpers
├── data/*.json             facts only
├── tasks/TASK-0NN.json     objectives
├── tools/                  42 tools + a registry
└── verifiers/              one per task + a registry

None of this is library code. It was copied into your project and it is yours to edit.

Change a fact, and watch grading follow

Run TASK-004 and note what the verifier expected:

npx @burn0/silo run --env demo --task TASK-004 --agent ./silo.agent.ts

answered 507500, expected 507500

Now open data/opportunities.json and make one opportunity bigger:

data/opportunities.json

{
  "id": "OPP-003",
  "name": "Vertex platform expansion",
  "amount": { "amount": 300000, "currency": "USD" },
  "stageId": "STG-004"
}

Run exactly the same command again:

answered 582500, expected 582500

Nothing but a number in a JSON file changed. No code was edited. The tool reported a new figure, the verifier expected the new figure, and the run still passed. OPP-003 sits in STG-004, which carries a 75% probability, so adding $100,000 of deal value adds $75,000 of weighted value. Both sides computed that independently from the same data.

This is what “deterministic verification” buys you. The verifier does not know 507500 — it derives the answer from the seeded world using the same helpers the tools use. Had the number been hardcoded, your edit would have made the verifier confidently wrong.

Change it back before continuing.

Add a task of your own

A task is a JSON file. Adding one is adding a file.

npx @burn0/silo task add --env demo --id TASK-007 \
  --title "Report Priya's open pipeline" \
  --instruction "Amara wants to know how much open pipeline Priya Nair (USR-003) is carrying. Report the total value of her open opportunities in US dollars." \
  --verifier VER-007 --difficulty easy

Created tasks/TASK-007.json

The instruction names who and what, and stops there. It does not say which tool to use or what the answer is.

Write the verifier that grades it

npx @burn0/silo verifier add VER-007 --env demo --task TASK-007 \
  --name "Priya's open pipeline reported correctly"

Created verifiers/VER-007.ts
Registered ver007 in verifiers/index.ts

The generated check fails on purpose, so an unimplemented verifier can never report a pass. Replace it:

verifiers/VER-007.ts

import { check, defineVerifier, optional } from "@burn0/silo";

import { type State, openPipelineFor } from "../state.js";
import { finalNumber, statesNumber } from "./shared.js";

const OWNER_ID = "USR-003";

export const ver007 = defineVerifier<State>({
  id: "VER-007",
  taskId: "TASK-007",
  name: "Priya's open pipeline reported correctly",
  check(final, initial, context) {
    const expected = openPipelineFor(initial, OWNER_ID).amount;
    const answered = finalNumber(context.agentOutput);

    return [
      check(
        "The reported open pipeline is correct",
        statesNumber(context.agentOutput, expected),
        `answered ${answered ?? "nothing"}, expected ${expected}`,
      ),
      optional(
        "Answering left the world unchanged",
        JSON.stringify(final) === JSON.stringify(initial),
        "state is untouched",
      ),
    ];
  },
});

openPipelineFor is a domain helper that already exists in state.ts — the same one the pipeline_summary tool uses. That is the pattern: write the rule once, and let both the tool and the grader read it.

Check your work before running

npx @burn0/silo env validate --env demo

OK	demo	data=9 tasks=7 tools=43 verifiers=7

Seven tasks and seven verifiers, so the new pair is wired up. Validation compiles the whole environment, not just the parts this task touches.

Run it

pipeline.agent.js

export default async function agent({ callTool }) {
  const summary = await callTool("pipeline_summary", { ownerId: "USR-003" });
  const { totalAmount } = summary.output;

  return { output: `Priya Nair is carrying $${totalAmount.amount} of open pipeline.` };
}

npx @burn0/silo run --env demo --task TASK-007 --agent ./pipeline.agent.js

  Task          TASK-007 — Report Priya's open pipeline
  Result        PASS
  Reward        1.00
  Checks        2 / 2
  Required      1 / 1

answered 245000, expected 245000

Prove the verifier can fail

A check that passes on no work is not a check. Point an agent that does not answer at the same task and confirm it fails. Do this once for every verifier you write. It is the cheapest insurance in the whole workflow, and it is the step most often skipped.

Where to go next

Environments

How data, state, tools, tasks and verifiers fit together.

Build From Scratch

A complete environment from an empty template.

Bring Your Own Agent

Wire up a real model loop.

Scoring

What pass, fail and reward actually mean.

Getting Started

Environments

Running Agents

Guides

Reference

Your First Environment

Look inside

Change a fact, and watch grading follow

Add a task of your own

Write the verifier that grades it

Check your work before running

Run it

Prove the verifier can fail

Where to go next

Environments

Build From Scratch

Bring Your Own Agent

Scoring

​Look inside

​Change a fact, and watch grading follow

​Add a task of your own

​Write the verifier that grades it

​Check your work before running

​Run it

​Prove the verifier can fail

​Where to go next

Environments

Build From Scratch

Bring Your Own Agent

Scoring

Look inside

Change a fact, and watch grading follow

Add a task of your own

Write the verifier that grades it

Check your work before running

Run it

Prove the verifier can fail

Where to go next