open-agent-compiler

Define agents once, as typed Python. Compile them to any agent runtime. Test them with mocks. Improve them with closed-loop optimization.

open-agent-compiler is a Python-first agent framework built around a compiler, not a runtime: agents are declarative Pydantic definitions — system prompts, tools, skills, workflows, permissions, subagents, and tests — and the framework turns that single source of truth into whatever each target runtime needs.

flowchart TB
    AD["AgentDefinition (Pydantic)<br/>prompt · tools · skills · workflow<br/>permissions · subagents · tests"]
    AD -- compile --> OC[".opencode/agents/*.md<br/>(OpenCode runtime)"]
    AD -- compile --> CC[".claude/agents/*.md<br/>(Claude Code)"]
    AD -- compile --> PI[".pi/agents/*.md<br/>(Pi agents)"]
    AD -- compile --> CX[".codex/agents/*.toml<br/>(Codex CLI)"]
    AD -- compile --> IS["InteractiveAgentSpec<br/>(LangChain / PydanticAI runnable)"]

Text version of this diagram

                ┌────────────────────────────────────────────┐
                │        AgentDefinition (Pydantic)          │
                │  prompt · tools · skills · workflow ·      │
                │  permissions · subagents · tests           │
                └──────────────┬─────────────────────────────┘
                               │ compile
      ┌────────────────────────┼────────────────────┬──────────────────┐
      ▼                        ▼                    ▼                  ▼
.opencode/agents/*.md   .claude/agents/*.md   .pi/agents/*.md   InteractiveAgentSpec
(OpenCode runtime)      (Claude Code)         (Pi agents)       (LangChain runnable)

Install

pip install open-agent-compiler
# or
uv add open-agent-compiler

Highlights

• Multi-dialect compiler — one agent tree compiles to OpenCode, Claude Code, Pi, and Codex agent formats, plus an in-process interactive tier.
• Per-target adaptation — autoloops tune the same agent per harness × model (including the realtime tier), with per-target promotion slots, a SQLite run store, and oac versions management.
• Evolve a coding harness — oac evolve <repo> builds a repo-tailored harness in an isolated clone and evolves it against the repo's own commits and a stronger-model teacher — including structural (workflow/tool) mutation, not just prompt text.
• Embedded testing — capability, tool, and agent tests live next to the definitions and run against mocks, so CI never needs credentials.
• Improvement loop — mutate prompts and parameters, evaluate against probes, keep what scores better, and promote winners — per model, in parallel.
• Scaffolding — oac init generates a full project (optionally with Docker, FastAPI, Postgres, cron, or a per-client personalized SaaS shape).
• oac CLI — compile, introspect, test, improve, and promote from the terminal.

Where to go next

New here? Follow the path:

1. Installation — get oac running.
2. Your First Agent — define, compile, and run an agent in ten minutes.
3. Philosophy & Assumptions — the mental model behind the framework.
4. Execution Tiers — the fast/slow split: in-process interactive agents vs compiled long-running workers.

Want to see features earn their keep? Each tutorial is a mini-project built around one feature: a triage bot (agent trees), a database reporting tool (tools + mocked tests), one agent on three models (variants), a self-improving agent (the improvement loop), and fast chat + slow worker (execution tiers).

Building something specific? The guides cover tools, workflows, skills, variants, testing, the improvement loop, and the interactive tier; the dialect pages cover each compile target; the CLI reference and troubleshooting round it out.

Prefer one long read? The original all-in-one guide still exists, and the field lessons — optimize the real goal, thinking models & scoring, tuning a local agent fleet — capture hard-won production experience.