open-agent-spec 1.2.4

YAML-first agent specs: run with `oa run` or generate a full Python project with `oa init`.

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.

Open Agent Stack