Open specification · OA
Open Agent Spec
Define AI agents as contracts, not scattered prompts. One YAML spec, typed inputs and outputs validated on every run, and a token bill you can attribute to a task.
Think OpenAPI or Terraform, but for AI agents.
Why it exists
Most agent systems are hard to reason about. Not because the models are bad, but because nothing about the agent is declared anywhere you can inspect.
- Outputs are not strictly typed
- Behaviour is buried in prompts
- Logic is split across Python, Markdown and framework abstractions
- Swapping models breaks things in subtle ways
- Token spend is invisible until the provider bill arrives, and cannot be attributed back to a task
The boundary OA enforces
input → LLM → validated output
A shape mismatch is the kind of thing that breaks a downstream system silently. This:
{"msg": "hello"}instead of this:
{"response": "hello"}Under OA the second one is the only one that gets through. The first fails validation and stops.
What the specification commits to
The boundary is enforced, not suggested
OA enforces input → LLM → validated output. If the output does not match the schema, the task fails fast with a validation error instead of returning something plausible that quietly breaks whatever reads it next.
An agent is a file you can review
Input schema, output schema, prompts and model configuration live in one YAML spec. Keep .agents/*.yaml in your repo, diff them in review, and call them from CI like any other artefact.
Cost is part of the contract
Every result carries normalised token usage and a best-effort dollar figure, with declarative controls to right-size reasoning depth per task. Spend is attributable before the invoice arrives, not after.
Run the spec, or generate the code
oa run executes a spec directly with no scaffolding step. oa init generates a Python project when you want to customise the implementation. The same spec backs both.
Install to working agent
Four commands. The aac layout is a repo-native .agents/ directory, so the specs live beside the code that calls them.
# Python 3.10+
pipx install open-agent-spec
# Create the agents-as-code layout
oa init aac
oa validate aac
# Run a spec directly — no scaffolding step
export OPENAI_API_KEY=your_key_here
oa run --spec .agents/example.yaml --task greet --input '{"name":"Alice"}' --quietIf you depend on contract validation, pin the contracts extra. Without it the runner skips contract validation with only a warning — which looks identical to passing. Install open-agent-spec[contracts] and pin the version your specs declare.
Repositories
Everything below is public. Read it, run it, or open an issue arguing with it.
open-agent-spec
The specification and the oa CLI
The spec, the schema it validates against, and the CLI that runs or scaffolds from it. MIT licensed, Python 3.10+, published to PyPI.
Open repositoryProtocoldacp
Distributed Agent Communication Protocol
How OA agents talk to each other: workflow orchestration, agent-to-agent messaging, session management and conditional routing for multi-agent systems.
Open repositoryContractsbehavioural-contracts
The constraint layer
The contracts extra that OA validates against. Without it the runner skips contract validation with a warning — which is why anything serious pins it explicitly.
Open repositoryOrganisationprime-vector
Everything else, in the open
The organisation: templates, example specs, and the discussions where the specification gets argued out in public.
Open repositoryThe specification is the easy half
Declaring agents as code is what makes the hard part tractable: getting a claim from the agent that formed it to the person who acts on it without losing what made it honest. That is the discipline we call Response Engineering.