Define AI agents with YAML. Generate working scaffolding instantly.
Open Agent Spec (OA) is a YAML specification for defining AI agents and generating working scaffolding.
Building AI agents today often requires manually wiring together:
- prompt templates
- LLM configuration
- task routing
- memory structures
- runtime logic
Open Agent Spec moves these concerns into a declarative specification.
Define an agent once in YAML and run it directly, or generate a project scaffold for customization.
You can think of OA as something similar to OpenAPI for services or Terraform for infrastructure, but for AI agents.
Install the CLI:
pip
pip install open-agent-specHomebrew (tap then install):
brew tap prime-vector/homebrew-prime-vector
brew install open-agent-spec
oa --versionpipx (isolated CLI):
pipx install open-agent-specSet your LLM API key (example for OpenAI):
export OPENAI_API_KEY=your_api_key_hereCreate an agent spec:
open_agent_spec: "1.0.9"
agent:
name: hello-world-agent
role: chat
intelligence:
type: llm
engine: openai
model: gpt-4
tasks:
greet:
description: Say hello to someone
input:
type: object
properties:
name:
type: string
required: [name]
output:
type: object
properties:
response:
type: string
required: [response]
prompts:
system: >
You greet people by name.
user: "{{ name }}"Run the agent directly from the spec:
oa run --spec agent.yaml --task greet --input '{"name":"Alice"}' --quietStore specs in a .agents/ directory at the repo root — like .github/workflows/ but for agents. Run them directly, or generate code from them.
oa init aac # scaffold .agents/ with an example spec
oa run --spec .agents/example.yaml --task greet --input '{"name":"CI"}' --quietThis repo's own .agents/ directory includes a CI failure repair agent that is called from a GitHub Actions workflow to auto-fix lint and formatting issues.
See docs/REFERENCE.md for details and bundled examples.
If you want to extend the implementation, generate a project scaffold:
oa init --spec agent.yaml --output ./agentThis produces a Python project you can customize.
agent/
├── agent.py
├── models.py
├── prompts/
├── requirements.txt
├── .env.example
└── README.md
Open Agent Spec (OA) intentionally keeps the specification minimal.
The goal is to define agents declaratively and generate consistent project scaffolding.
Tasks in an OA specification are intended to represent atomic units of capability for an agent, rather than complex workflows. Higher-level orchestration can be built on top of these primitives by external systems.
OA does not prescribe:
- runtime orchestration
- governance systems
- evaluation frameworks
These concerns can be layered on top by different runtimes, frameworks, or architectures.
Many teams building agents end up recreating the same infrastructure:
- agent scaffolding
- prompt organization
- model configuration
- task definitions
OA provides a consistent way to define agents once and generate a working structure automatically.
Several projects are exploring ways to standardize how AI agents are defined and orchestrated.
Open Agent Spec (OA) focuses specifically on developer-facing scaffolding from a declarative YAML specification.
The goal is to make agent architecture easier to reason about and quicker to implement.
| Command | Purpose |
|---|---|
oa init --spec … --output … |
Generate project from YAML |
oa init --template minimal --output … |
Same with bundled spec |
oa init aac |
.agents/ + example spec only |
oa run --spec … [--task …] [--input JSON] [--quiet] |
Run task without codegen |
oa update --spec … --output … |
Regenerate into existing dir |
oa init … --dry-run |
Validate only |
oa --help| Resource | Contents |
|---|---|
| docs/REFERENCE.md | Full spec, engines, templates |
| Repository | Source, issues, CI |
“CLI command is oa (formerly oas in older releases).”
MIT — see LICENSE.