Build an Environment From Scratch

This walks through building a small support-desk environment from blank. Every command and every output below is from an actual session — you can follow along and get the same results. The order matters. Each step depends on the one before it, and doing them out of sequence means editing generated files by hand.

1. Scaffold

npx @burn0/silo init helpdesk --template blank

Created environment "helpdesk" from Blank at ./.silo/environments/helpdesk

Blank gives you the contract wired up and nothing in it:

.silo/environments/helpdesk/
├── silo.environment.json
├── index.ts               the three exports
├── environment.ts         returns {}
├── state.ts               export type State = Record<string, unknown>
├── data/
├── tasks/
├── tools/index.ts         an empty registry
└── verifiers/index.ts     an empty registry

2. Add data

Facts only — no computed values.

tickets.json

[
  { "id": "TKT-001", "subject": "Card declined at checkout", "status": "open", "priority": "high", "customerId": "CUS-001", "assigneeId": null, "openedDate": "2026-03-02" },
  { "id": "TKT-002", "subject": "Cannot reset password", "status": "open", "priority": "normal", "customerId": "CUS-002", "assigneeId": "AGT-001", "openedDate": "2026-03-11" },
  { "id": "TKT-003", "subject": "Duplicate invoice received", "status": "resolved", "priority": "normal", "customerId": "CUS-001", "assigneeId": "AGT-002", "openedDate": "2026-02-18" },
  { "id": "TKT-004", "subject": "Export fails on large reports", "status": "open", "priority": "urgent", "customerId": "CUS-003", "assigneeId": null, "openedDate": "2026-01-29" }
]

agents.json

[
  { "id": "AGT-001", "name": "Rosa Iqbal", "available": true },
  { "id": "AGT-002", "name": "Kenji Adeyemi", "available": false }
]

npx @burn0/silo data add tickets --env helpdesk --file ./tickets.json
npx @burn0/silo data add agents  --env helpdesk --file ./agents.json

Created data/tickets.json
Created data/agents.json

Notice the shape of this seed: two tickets are unassigned, and only one of the two agents is available. That is deliberate — it gives a task a correct answer and a wrong-but-plausible one.

3. Write `state.ts` before anything else

This is the step people skip, and it costs the most. Scaffolded tools and verifiers import State and are generated against it, so writing state first means the stubs come out correct.

state.ts

export type TicketStatus = "open" | "resolved" | "closed";
export type Priority = "low" | "normal" | "high" | "urgent";

export type Ticket = {
  id: string;
  subject: string;
  status: TicketStatus;
  priority: Priority;
  customerId: string;
  assigneeId: string | null;
  openedDate: string;
};

export type Agent = { id: string; name: string; available: boolean };

export type State = {
  now: string;
  tickets: Record<string, Ticket>;
  agents: Record<string, Agent>;
};

export function indexById<T extends { id: string }>(rows: T[]): Record<string, T> {
  return Object.fromEntries(rows.map((row) => [row.id, row]));
}

export function daysOpen(state: State, ticket: Ticket): number {
  const start = Date.parse(`${ticket.openedDate}T00:00:00.000Z`);
  const end = Date.parse(`${state.now}T00:00:00.000Z`);

  return Math.round((end - start) / 86_400_000);
}

/** An open ticket nobody owns. These are what a triage task is about. */
export function isUnassigned(ticket: Ticket): boolean {
  return ticket.status === "open" && ticket.assigneeId === null;
}

Two things worth copying: now is in state because the domain has a clock, and isUnassigned is a helper because both a tool and a verifier will need that definition.

4. Build the world

environment.ts

import { type Agent, type State, type Ticket, indexById } from "./state.js";

import agentsData from "./data/agents.json" with { type: "json" };
import ticketsData from "./data/tickets.json" with { type: "json" };

/** Fixed so that "days open" is reproducible. */
export const SIMULATION_NOW = "2026-03-16";

export function createState(): State {
  return structuredClone({
    now: SIMULATION_NOW,
    tickets: indexById(ticketsData as Ticket[]),
    agents: indexById(agentsData as Agent[]),
  });
}

structuredClone is not optional. Node caches imported JSON for the process lifetime, so without it the second rollout starts from whatever the first one left behind — which presents as flaky grading, not an obvious bug.

5. Scaffold the tools

npx @burn0/silo tool add list_tickets --env helpdesk \
  --description "List tickets, optionally filtered by status or whether they are unassigned."
npx @burn0/silo tool add list_agents --env helpdesk \
  --description "List support agents and whether each is currently available to take work."
npx @burn0/silo tool add assign_ticket --env helpdesk \
  --description "Assign an open ticket to an available agent."

Created tools/list-tickets.ts
Registered listTickets in tools/index.ts
Next: implement run() in tools/list-tickets.ts (look for TODO).

Three tools for two collections is the minimum here: the agent must be able to see the queue, see who can take work, and act. Anything it cannot see through a tool, it cannot know.

6. Implement them

The generated stub throws on purpose. Replace the TODO:

tools/assign-ticket.ts

export const assignTicket = defineTool<State>({
  name: "assign_ticket",
  description:
    "Assign an open ticket to an available agent. Refuses if the ticket is not open or the agent is unavailable.",
  inputSchema: {
    type: "object",
    properties: {
      ticketId: { type: "string", description: "Ticket ID, e.g. 'TKT-001'." },
      agentId: { type: "string", description: "Agent ID, e.g. 'AGT-001'." },
    },
    required: ["ticketId", "agentId"],
    additionalProperties: false,
  },
  run(state, input) {
    const ticket = state.tickets[String(input["ticketId"] ?? "")];
    if (!ticket) throw toolError("not_found", `Ticket was not found.`);

    const agent = state.agents[String(input["agentId"] ?? "")];
    if (!agent) throw toolError("not_found", `Agent was not found.`);

    if (ticket.status !== "open") {
      throw toolError("invalid_state", `Ticket ${ticket.id} is ${ticket.status}, not open.`);
    }

    if (!agent.available) {
      throw toolError("not_allowed", `Agent ${agent.name} is not available to take work.`);
    }

    ticket.assigneeId = agent.id;

    return { assigned: { ticketId: ticket.id, agentId: agent.id, agentName: agent.name } };
  },
});

The business rules live in the tool. Because assign_ticket refuses an unavailable agent, “assign these to someone who can take them” becomes a real task rather than a formality.

7. Add a task

npx @burn0/silo task add --env helpdesk --id TASK-001 \
  --title "Triage the unassigned queue" \
  --instruction "Nobody is looking at the unassigned tickets. Assign every open ticket that has no owner to an agent who is actually available to take it." \
  --verifier VER-001 --difficulty easy

Created tasks/TASK-001.json

The instruction states the outcome and nothing else. It does not name the tools, say how many tickets there are, or mention that one agent is unavailable — discovering that is the work.

8. Scaffold and write the verifier

npx @burn0/silo verifier add VER-001 --env helpdesk --task TASK-001 \
  --name "Unassigned tickets triaged to available agents"

Created verifiers/VER-001.ts
Registered ver001 in verifiers/index.ts
Next: replace the failing TODO check in verifiers/VER-001.ts.

verifiers/VER-001.ts

export const ver001 = defineVerifier<State>({
  id: "VER-001",
  taskId: "TASK-001",
  name: "Unassigned tickets triaged to available agents",
  check(final, initial) {
    const needed = Object.values(initial.tickets).filter(isUnassigned);

    const assigned = needed.filter((ticket) => final.tickets[ticket.id]?.assigneeId !== null);

    const toAvailableAgents = needed.every((ticket) => {
      const assigneeId = final.tickets[ticket.id]?.assigneeId;

      return assigneeId === null || initial.agents[assigneeId]?.available === true;
    });

    return [
      check(
        "Every unassigned open ticket now has an owner",
        needed.length > 0 && assigned.length === needed.length,
        `${assigned.length} of ${needed.length} assigned`,
      ),
      check(
        "Work only went to agents who were available",
        toAvailableAgents,
        "no ticket assigned to an unavailable agent",
      ),
      optional(
        "Tickets that already had an owner were left alone",
        untouched,
        "existing assignments preserved",
      ),
    ];
  },
});

The set of tickets that needed an owner is derived from initial, not listed here. Add another unassigned ticket to the seed data and this check strengthens automatically.

9. Validate — this is the stopping condition

npx @burn0/silo env validate --env helpdesk

OK	helpdesk	data=2 tasks=1 tools=3 verifiers=1

Do not skip to running. Validation compiles the whole environment, including the tools this task never calls. A run proves one path works; validation proves the environment is sound. The counts are a second check: three tools means all three registered. If you wrote a tool and the number did not move, it is not in the barrel.

10. Run it

helpdesk.agent.ts

export default async function agent({ callTool }: AgentInput) {
  const queue = await callTool("list_tickets", { unassignedOnly: true });
  const staff = await callTool("list_agents", { availableOnly: true });

  const tickets = (queue.output as { results: Array<{ id: string }> }).results;
  const agents = (staff.output as { results: Array<{ id: string }> }).results;

  const assigned: string[] = [];

  for (const [index, ticket] of tickets.entries()) {
    const agent = agents[index % agents.length]!;
    const result = await callTool("assign_ticket", { ticketId: ticket.id, agentId: agent.id });

    if (!result.isError) assigned.push(`${ticket.id} → ${agent.id}`);
  }

  return { output: `Assigned ${assigned.length} tickets: ${assigned.join(", ")}.` };
}

npx @burn0/silo run --env helpdesk --task TASK-001 --agent ./helpdesk.agent.ts

  Silo Run

  Task          TASK-001 — Triage the unassigned queue
  Result        PASS
  Reward        1.00

  Tool calls    4
  Successful    4
  Errors        0

  Checks        3 / 3
  Required      2 / 2

11. Prove the verifier can fail

A gate that cannot fail is worse than no gate. Point a different agent at the same task — one that does not do the work:

  Result        FAIL
  Reward        0.67
  Required      1 / 2
  ✗ Every unassigned open ticket now has an owner

Now you know the check discriminates. Run this once for every verifier you write.

What to do next

Add a second task that produces an answer rather than a change — “how many tickets have been open more than 30 days?” — and derive the expected figure in the verifier using daysOpen.
Add the awkward rows: a ticket assigned to an agent who has since become unavailable.
Record a passing run’s result.json as a baseline, so a change in behaviour shows up as a diff.

Getting Started

Environments

Running Agents

Guides

Reference

Build an Environment From Scratch

1. Scaffold

2. Add data

3. Write `state.ts` before anything else

4. Build the world

5. Scaffold the tools

6. Implement them

7. Add a task

8. Scaffold and write the verifier

9. Validate — this is the stopping condition

10. Run it

11. Prove the verifier can fail

What to do next

​1. Scaffold

​2. Add data

​3. Write state.ts before anything else

​4. Build the world

​5. Scaffold the tools

​6. Implement them

​7. Add a task

​8. Scaffold and write the verifier

​9. Validate — this is the stopping condition

​10. Run it

​11. Prove the verifier can fail

​What to do next

1. Scaffold

2. Add data

3. Write `state.ts` before anything else

4. Build the world

5. Scaffold the tools

6. Implement them

7. Add a task

8. Scaffold and write the verifier

9. Validate — this is the stopping condition

10. Run it

11. Prove the verifier can fail

What to do next