Skip to main content

Open Agent Spec (OA)

Define AI agents as contracts, not scattered prompts.

PyPI version Python License

Open Agent Spec lets you define an agent once in YAML, validate inputs and outputs against a schema, and either run it directly with oa run or generate a Python scaffold with oa init.

Why This Exists

Most agent systems are hard to reason about:

  • outputs are not strictly typed
  • behaviour is buried in prompts
  • logic is split across Python, Markdown, and framework abstractions
  • swapping models often breaks things in subtle ways

The Idea

Open Agent Spec treats an agent like infrastructure.

Think OpenAPI or Terraform, but for AI agents.

You define:

  • input schema
  • output schema
  • prompts
  • model configuration

Then OA enforces the boundary:

input -> LLM -> validated output

If the output does not match schema, the task fails fast with a validation error.

For example, this shape mismatch can silently break downstream systems:

{"msg":"hello"}

instead of:

{"response":"hello"}

Agents as Code — OA init spec, spec run, LLM execution, tasks executed

Super Quick Start

Install (Python 3.10+):

pipx install open-agent-spec
oa init aac
oa validate aac
export OPENAI_API_KEY=your_key_here
oa run --spec .agents/example.yaml --task greet --input '{"name":"Alice"}' --quiet

With OA you can:

  • define tasks, prompts, model config, and expected I/O in YAML
  • run a spec directly without generating code first
  • keep .agents/*.yaml in your repo and call them from CI
  • generate a Python project scaffold when you want to customize implementation

First Run

Shortest path from install to a working agent:

1. Create the agents-as-code layout (aac = repo-native .agents/ directory):

oa init aac

This creates:

.agents/
├── example.yaml   # minimal hello-world spec
├── review.yaml    # code-review agent that accepts a diff file
├── change.diff    # sample diff for immediate review-agent testing
└── README.md      # quick usage notes

2. Validate the generated specs:

oa validate aac

3. Set an API key for the engine in your spec (OpenAI by default):

export OPENAI_API_KEY=your_key_here

4. Run the example agent:

oa run --spec .agents/example.yaml --task greet --input '{"name":"Alice"}' --quiet

--quiet prints the task output JSON only, good for piping to jq or scripting:

{
  "response": "Hello Alice!"
}

Omit --quiet for the full execution envelope with Rich formatting.

5. Run the review agent with the bundled sample diff:

oa run --spec .agents/review.yaml --task review --input .agents/change.diff --quiet

Or review your own change:

git diff > change.diff
oa run --spec .agents/review.yaml --task review --input change.diff --quiet

Write Your Own Spec

Start from this shape:

open_agent_spec: "1.2.9"

agent:
  name: hello-world-agent
  role: chat

intelligence:
  type: llm
  engine: openai
  model: gpt-4o

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 }}"

Validate first, then run:

oa validate --spec agent.yaml
oa run --spec agent.yaml --task greet --input '{"name":"Alice"}' --quiet

Generate a Python Scaffold

If you want editable generated code instead of running the YAML directly:

oa init --spec agent.yaml --output ./agent

Generated structure:

agent/
├── agent.py
├── models.py
├── prompts/
├── requirements.txt
├── .env.example
└── README.md

Core Idea

Most agent projects end up hand-rolling the same pieces:

  • prompt templates
  • model configuration
  • task definitions
  • routing glue
  • runtime wrappers

OA moves those concerns into a declarative spec so they can be reviewed, versioned, and reused.

The intended model is:

  • spec defines the agent contract
  • oa run executes the spec directly
  • oa init generates a starting implementation when you need code
  • external systems can orchestrate multiple specs however they want

OA deliberately does not prescribe:

  • orchestration
  • evaluation
  • governance
  • long-running runtime architecture

Common Commands

Command Purpose
oa init aac Create .agents/ with starter specs
oa validate aac Validate all specs in .agents/
oa validate --spec agent.yaml Validate one spec
oa run --spec agent.yaml --task greet --input '{"name":"Alice"}' --quiet Run one task directly from YAML
oa init --spec agent.yaml --output ./agent Generate a Python scaffold
oa update --spec agent.yaml --output ./agent Regenerate an existing scaffold

More Detail

Resource Contents
openagentspec.dev Project website
docs/REFERENCE.md Spec structure, engines, templates, .agents/ usage
Repository Source, issues, workflows

Notes

  • The CLI command is oa (not oas).
  • Python 3.10+ is required.
  • oa run requires the relevant provider API key for the engine in your spec.

About

  • OA Open Agent Spec was dreamed up by Andrew Whitehouse in late 2024, with a desire to give structure and standardiasation to early agent systems
  • In early 2025 Prime Vector was formed taking over the public facing project

License

MIT | see LICENSE.

Open Agent Stack

Metadata

Release files for open-agent-spec 1.2.9

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.9
File Size Uploaded Provenance Actions
open_agent_spec-1.2.9.tar.gz 86.6 MB Without provenance Details for open_agent_spec-1.2.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for open-agent-spec 1.2.9
File Interpreter ABI Platform Actions
open_agent_spec-1.2.9-py3-none-any.whl Python 3 none any Details for open_agent_spec-1.2.9-py3-none-any.whl

Total release size: 86.7 MB

Release files / open_agent_spec-1.2.9.tar.gz

Download URL open_agent_spec-1.2.9.tar.gz
Size 86.6 MB
Tags Source
SHA-256 checksum
How to use checksums
846f43cf1f5c50213e5f5848aa1beaf984e93e8bb8d2d43e87c61956411a3e2d
BLAKE2b-256 checksum
How to use checksums
0c8043e50367c0a918c0b1c52816d4dc66db5caf5f41d211024580cf3489fe9b
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.9-py3-none-any.whl

Download URL open_agent_spec-1.2.9-py3-none-any.whl
Size 63.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d38cccea1985f229a90223f7bd1f61b1db178bd99ac68505ef9e102dda16042
BLAKE2b-256 checksum
How to use checksums
8ea06c6ce334ff7a0bca332747908fc54b82ad8ac8b6e443283ae50796882870
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.9

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