Build an Environment
Turn a real workflow into a bounded environment with observable state and a checkable outcome.
Build an environment when the work depends on your data, tools, permissions, or verification rules. The goal is not to give an agent everything. It is to give the worker exactly the world required to complete one class of work reliably.
Write the environment contract
Start with a one-page contract:
| Field | What to write |
|---|---|
| User | Who enters the environment and what they already know |
| Job | The recurring real-world task this environment supports |
| Inputs | Files, records, measurements, parameters, or events it receives |
| Actions | Tools and state changes available inside the boundary |
| Output | The artifact or state change produced at the end |
| Definition of done | The checks that make the result acceptable |
| Guardrails | Data, cost, safety, permission, and operating limits |
If the contract contains several unrelated outputs or review methods, split it into smaller environments.
Build it in layers
Define one checkable outcome
Name the result as a noun plus a condition: “a cited market brief with every claim linked,” “a deployment whose health checks pass,” or “a ray-tracing comparison that records optical path length for every material.”
Model the minimum state
Decide what the worker must see and change. Prefer explicit fields, parameters, files, and tables over hidden prompt context. Important state should remain inspectable after the run.
Add only the necessary tools
Connect the smallest toolset that can complete the task. Separate read tools from write tools, make irreversible actions explicit, and default external systems to read-only while testing.
Put controls around risk
Define spend limits, allowed domains, data boundaries, operating ranges, approval steps, and stop conditions. Show these constraints in the environment instead of relying on memory.
Instrument the result
Capture inputs, actions, versions, outputs, and verification results. For a simulation this may be a reproducible parameter set and expected invariant; for business work it may be a before-and-after snapshot plus reviewer signoff.
Test a known case and an edge case
First reproduce an accepted result. Then use a case that should fail or stop. A trustworthy environment makes both success and refusal understandable.
Package a clean starting state
Remove private test data, keep one safe example, document the controls, and save a baseline version. That package can become a reusable template.
A convincing visualization is not the same as a validated model. For medical, legal, financial, safety-critical, or engineering decisions, state the model's limits and require the appropriate expert review.
Example: a research environment
Job: compare three competing explanations for a change in customer churn.
Inputs: anonymized event data, product-release history, interview notes, and a metric dictionary.
Actions: query data, create plots, test hypotheses, and draft a report. No production writes and no access to direct identifiers.
Output: a short evidence table followed by the strongest explanation, counter-evidence, and the next experiment.
Done when: every claim points to a query or source, the analysis can be rerun, and a reviewer can distinguish observed facts from interpretation.
This same structure—job, state, tools, limits, output, and evidence—scales from an educational physics lab to a deployment workspace.
Connect it to XO
Under the hood, an environment can use an agent runtime such as XO Cowork, Claude Code, Codex, OpenClaw, or Hermes. Connect structured tools through the XO Cowork API or expose supported capabilities through the XO MCP Server. The runtime can change; the environment contract should remain stable.