Metadata-Version: 2.4
Name: open-agent-spec
Version: 1.2.5
Summary: YAML-first agent specs: run with `oa run` or generate a full Python project with `oa init`.
Project-URL: Homepage, https://www.openagentstack.ai
Project-URL: Repository, https://github.com/prime-vector/open-agent-spec
Project-URL: Documentation, https://github.com/prime-vector/open-agent-spec/blob/main/docs/REFERENCE.md
Author-email: Andrew Whitehouse <andrewswhitehouse@gmail.com>
License: MIT
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.3.0
Requires-Dist: dacp>=0.3.3
Requires-Dist: jinja2>=3.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: setuptools>=69.0.0
Requires-Dist: tomli>=1.0.0; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: allure-pytest>=2.0.0; extra == 'dev'
Requires-Dist: behavioural-contracts==0.1.2; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: dacp>=0.3.3; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-html>=3.0.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-setuptools>=69.0.0; extra == 'dev'
Requires-Dist: types-toml>=0.10.0; extra == 'dev'
Description-Content-Type: text/markdown

# Open Agent Spec (OA)

Define AI agents with YAML. Generate working scaffolding instantly.

![PyPI version](https://img.shields.io/pypi/v/open-agent-spec)
![Python](https://img.shields.io/pypi/pyversions/open-agent-spec)
![License](https://img.shields.io/badge/license-MIT-blue)

**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**

```bash
pip install open-agent-spec
```

**Homebrew** (tap then install):

```bash
brew tap prime-vector/homebrew-prime-vector
brew install open-agent-spec
oa --version
```

**pipx** (isolated CLI):

```bash
pipx install open-agent-spec
```

Set your LLM API key (example for OpenAI):

```bash
export OPENAI_API_KEY=your_api_key_here
```

Create an agent spec:

```yaml
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:

```bash
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.

```bash
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](.agents/ci-failure-repair.yaml) that is called from a GitHub Actions workflow to auto-fix lint and formatting issues.

See [docs/REFERENCE.md](docs/REFERENCE.md#agents-as-code-agents) for details and bundled examples.

---

# Generate a Project Scaffold (Optional)

If you want to extend the implementation, generate a project scaffold:

```bash
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 |

```bash
oa --help
```

---

## More detail

| Resource | Contents |
|----------|----------|
| [docs/REFERENCE.md](https://github.com/prime-vector/open-agent-spec/blob/main/docs/REFERENCE.md) | Full spec, engines, templates |
| [Repository](https://github.com/prime-vector/open-agent-spec) | Source, issues, CI |

[![PyPI](https://img.shields.io/pypi/v/open-agent-spec)](https://pypi.org/project/open-agent-spec/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Historical Changes

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

---

## License

MIT — see [LICENSE](LICENSE).

[Open Agent Stack](https://www.openagentstack.ai)
