Open Agent Spec (OA)
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.
Quick Start
Install the CLI:
pip
pip install open-agent-spec
Homebrew (tap then install):
brew tap prime-vector/homebrew-prime-vector
brew install open-agent-spec
oa --version
pipx (isolated CLI):
pipx install open-agent-spec
Set your LLM API key (example for OpenAI):
export OPENAI_API_KEY=your_api_key_here
Create an agent spec:
open_agent_spec: "1.2.3"
agent:
name: hello-world-agent
role: chat
intelligence:
type: llm
engine: openai
model: gpt-4o # or any model your account has access to
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 validate --spec agent.yaml # schema check only (no model call)
oa run --spec agent.yaml --task greet \
--input '{"name":"Alice"}' --quiet # model call (requires OPENAI_API_KEY)
Agents as Code
Store 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"}' --quiet
This 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.
Generate a Project Scaffold (Optional)
If you want to extend the implementation, generate a project scaffold:
oa init --spec agent.yaml --output ./agent
This produces a Python project you can customize.
Generated Project Structure
agent/
├── agent.py
├── models.py
├── prompts/
├── requirements.txt
├── .env.example
└── README.md
Design Philosophy
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.
Why OA?
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.
Related Work
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.
Commands
| 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
More detail
| Resource | Contents |
|---|---|
| docs/REFERENCE.md | Full spec, engines, templates |
| Repository | Source, issues, CI |
Historical Changes
“CLI command is oa (formerly oas in older releases).”
License
MIT — see LICENSE.
Metadata
Release files for open-agent-spec 1.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| open_agent_spec-1.2.4.tar.gz | 17.9 MB | Without provenance | Details for open_agent_spec-1.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| open_agent_spec-1.2.4-py3-none-any.whl | Python 3 | none | any | Details for open_agent_spec-1.2.4-py3-none-any.whl |
Total release size: 17.9 MB
Release files / open_agent_spec-1.2.4.tar.gz
| Download URL | open_agent_spec-1.2.4.tar.gz |
|---|---|
| Size | 17.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10e01dc2a02393d30ae764f4251f588cbf633a5636e8563664d9511225a9b0ab
|
|
BLAKE2b-256 checksum How to use checksums |
6eccdb2861662d4f40262b535554a87c94d00424d24a1c43f9c5bb81d7cd1ea0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.5
|
Release files / open_agent_spec-1.2.4-py3-none-any.whl
| Download URL | open_agent_spec-1.2.4-py3-none-any.whl |
|---|---|
| Size | 59.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
184898f22d07735d33694a3219609cf1f76a257d7bd327fee51387e708b4e204
|
|
BLAKE2b-256 checksum How to use checksums |
5e1f4ac0b4f80dd9d62a6fe113dc557af27829bdf498637a3f294decb2a6f950
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.5
|
Security for open-agent-spec 1.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.