Agent Systems · core
Agent Environment Contracts
Deterministic bootstrap, dependency and runtime discovery, readiness probes, isolated workspaces, and explicit validation commands.
Mental model
Treat the development environment as an API offered to the agent: bootstrap has declared inputs, readiness has observable outputs, and every writable or networked capability has a boundary. If a fresh session cannot establish readiness mechanically, the environment contract is incomplete.
How to study Agent Environment Contracts
Begin by restating the mental model in your own words, then connect it to a concrete system you have built or operated. Name the mechanism, the constraint it addresses, and the trade-off it introduces. Use OpenAI — Harness engineering, Model Context Protocol — Roots to check details, but close the source before writing your explanation. Retrieval is the learning step; rereading is only preparation.
Next, compare Agent Environment Contracts with Repository Intelligence, Agent Permissions & Sandboxing, Coding Agent Systems. Ask what changes in correctness, latency, resource use, operability, and failure recovery. Complete Define an agent-readable environment contract and preserve the command, input, output, and one failed attempt as evidence. Finish by explaining the idea without jargon to someone who has not studied the track.
Proof of understanding
- Explain the mechanism from first principles and identify the state it reads or changes.
- Give one situation where the concept is the right choice and one where it is not.
- Predict a realistic failure mode before running the drill, then compare the prediction with evidence.
- Connect the result to a roadmap or build artifact instead of treating the concept as isolated trivia.
Where it matters
Per-worktree development servers, reproducible setup scripts, CI parity, local observability stacks, and sandbox readiness checks.
Common mistakes
- Assuming an undeclared global tool or manually prepared service exists
- Starting work before checking that dependencies and required services are ready
- Sharing mutable ports, databases, or build output across concurrent agent runs
Learn from primary sources
- OpenAI — Harness engineering (article)
- Model Context Protocol — Roots (doc)
Practice and explain it back
Define an agent-readable environment contract
Implement environmentContract(worktreeId) returning {bootstrap, readiness, workspace, capabilities}. bootstrap and readiness must each contain two runnable commands. workspace must include the supplied worktreeId and distinct port, database, and output identifiers derived from it. capabilities must explicitly list filesystem, network, and secrets as allow, deny, or scoped.
Expected evidence: A reproducible bootstrap/readiness contract whose mutable resources are isolated per worktree.
Open the interactive drill →Review prompts
- Why is 'the project works on my machine' an unusable environment contract for an autonomous coding agent, and what evidence makes the contract reproducible?
Build evidence
Build a Complete Coding-Agent Harness
Build a repository-local harness that can take one bounded engineering task from initialization through implementation, verification, durable handoff, and explicit termination without relying on hidden machine state or chat memory.
- A fresh isolated workspace can bootstrap and prove readiness from repository-local commands
- Instruction scopes, allowed edit roots, capabilities, budgets, and escalation triggers are explicit and mechanically inspectable
- The run persists goal, progress, evidence, blockers, and the next safe action across a forced restart
- A checker gathers independent evidence and can reject an unsupported maker claim
- The lifecycle terminates only as complete, blocked, failed, cancelled, or escalated with durable evidence