Corey James- 33schema contracts governing AgentOS handoffs
- 12semantic rules checking each API reference
- ≈2,000lines of Rust in the harness validator
Contracts at every handoff
Long agent runs drift when the handoffs between agents are prose, because each agent reinterprets what the last one meant. In AgentOS I made every handoff a contract and chose JSON Schema as the contract language. The *.schema.json contracts cover work-order sources, authoring plans, work packages and the structured output of model checkers.
Every seam is checked on both sides, so a malformed artefact cannot pass through a component that trusts its upstream. The PostgreSQL work graph and its schemas are the truth; Markdown views are generated from them, and edits to those views are discarded.
Diagnostics that name the fix
Work-order authoring starts from an operator-only source document. When it fails validation, the diagnostic names the exact field and the fix, such as a missing deliverable class or a team larger than the ceiling of twelve, which keeps authoring from turning into trial and error.
The schema for a model checker's verdict is flat and closed and matches the vendors' structured-output modes, so a verdict comes back as data. Nested and open schemas are where model output drifts. On the Rust side, contracts are checked with the jsonschema crate and hashed in canonical form. Why the handoffs had to become contracts is the subject of Why long agent runs fail.
Fields only from real calls
Connecting an API for agents usually starts with someone reading documentation and guessing which fields are real. In the sibling platform for third-party APIs in FAFO Core and Function Forge, I decided a field counts only once a real call has returned it. A two-pass normaliser does the work, starting from an OpenAPI 3.x document or a hand-written seed.
A semantic validator checks the canonical API reference, and the platform exposes no tools for an API until its validation harness passes, so the schema describes the API as it behaves. That platform's build is the story in Closed by evidence.
Validation in the harness
If every tool validates its own input, a fleet with hundreds of tools ends up with hundreds of slightly different validators. In Agent Swarm I put validation in the harness, as the first step of the frozen pipeline every tool call passes through. The validator applies draft-07 validation and the OpenAI strict-mode rules, plus structural pre-checks such as the depth of a peer-call chain, before parameters are normalised and authorised.
See Tools are the platform. I use schemas to take ambiguity out of systems where many agents hand work to one another. The validators are the standard Rust and Python libraries; the contracts, the seam discipline and the evidence rule for API fields are mine.
I put the checks where a bad artefact would otherwise pass unnoticed.