Skip to main content

Open Agent Spec (OA)

Define AI agents with YAML. Generate working scaffolding instantly.

PyPI version Python License

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

PyPI Python 3.10+ License: MIT


Historical Changes

“CLI command is oa (formerly oas in older releases).”


License

MIT — see LICENSE.

Open Agent Stack

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)

Source distribution for open-agent-spec 1.2.4
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)

Table of built distributions (wheels) for open-agent-spec 1.2.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page