OpenAgentPack

English | 简体中文

Manage, review, and migrate cloud AI agents with Git and YAML.

The open-source IaC control plane for managed AI agents.

Important

OpenAgentPack is in beta. Public APIs and the agents.yaml schema may change before 1.0. See the changelog.

One agents.yaml defines an agent's environment, model, instructions, tools, skills, MCP servers, vaults, and credentials. Review every change in a PR, preview it with plan, and apply it when ready — instead of rebuilding the same agent through console clicks.

• Reviewable agent assets — keep prompts, tools, skills, and configuration in Git; reuse, roll back, and hand them off.
• Predictable changes — validate → plan → apply previews creates, updates, and deletes before changing remote resources.
• Portable core declaration — target Bailian, Qoder, Claude, or Volcengine Ark with an explicit provider capability contract.

npm install -g @openagentpack/cli
agents init
# Configure one provider's credentials, then:
agents validate && agents plan

Run the 5-minute quick start · View provider support · Browse runnable examples · Roadmap

Why now

Agents are moving from personal tools to enterprise digital workers. But the things that make an agent valuable — its prompts, skills, knowledge files, tools, and runtime configuration — still live mainly inside cloud-provider consoles.

These are business assets. They should be managed, reviewed, handed over, reproduced, and migrated like code, data, and documents — not trapped as a pile of clicks in one console.

Why OpenAgentPack

OpenAgentPack puts a declarative control plane between the agent and the cloud platform. The enterprise owns the declaration; provider adapters render it into real managed agents on Bailian, Qoder, Claude, or Volcengine Ark.

The goal is to make an agent an enterprise-controlled, portable, and inheritable digital asset.

Declaration and portability: the agent as a blueprint

Borrowing Docker's declarative idea, OpenAgentPack brings everything that determines what an agent is — model, instructions, tools, skills, environment, files, and credential references — into one agents.yaml blueprint. The blueprint can live in Git, pass through pull-request review, reproduce an agent, and move across providers.

State and governance: plan before execution

Borrowing Terraform's state-driven workflow, OpenAgentPack keeps desired config, local state, and remote state distinct. plan previews creates, updates, and deletes; apply executes them in dependency order; drift detection finds console-side changes; and a previous declaration can restore a known-good configuration.

Validation and experience: Playground as the showroom

Even a precise blueprint needs to be experienced. Playground runs real sessions from the same declaration and lets teams exercise the same scenario against different providers. Provider comparison becomes an observable result, not only a capability matrix.

OpenAgentPack uses a Docker-like declaration to draw the agent blueprint, a Terraform-like state model to manage construction and acceptance, and Playground as the showroom — so enterprises can manage agents the way they manage code.

The mechanics are a single agents.yaml, a validate → plan → apply workflow, content-hash diffing, dependency-aware ordering, and drift recovery. The YAML remains the source of truth. See Agents as code for the mental model and CONTEXT.md for the precise vocabulary.

• Declarative — one agents.yaml describes your whole agent stack. Commit it, review it in a PR, roll it back.
• Terraform-style workflow — validate → plan → apply. Preview every create / update / delete before it happens.
• Multi-provider — reuse the core declaration across Bailian, Qoder, Claude, and Volcengine Ark; the capability contract makes native, emulated, and unsupported differences explicit.
• Incremental — content-hash diffing updates only what actually changed; no redundant API calls.
• Dependency-aware — Environment → Skill → Agent are created in topological order; a failed dependency skips its dependents instead of leaving half-built state.
• Drift recovery — detects when remote config has drifted from your declaration and reconciles it. The YAML is always the single source of truth.

Demo

CLI workflow

Local Playground

agents playground launches a local WebUI, fetches the matching @openagentpack/playground package on demand, and opens it in your browser. Use --provider to target bailian, qoder, ark, or claude.

playground.mp4

Quick start

agents init            # interactive wizard writes a starter agents.yaml
agents validate        # offline YAML check, no API calls
agents plan            # preview create / update / delete
agents apply -y        # apply changes
agents destroy         # tear down managed resources

A minimal config:

version: "1"

providers:
  bailian:
    api_key: ${DASHSCOPE_API_KEY}
    workspace_id: ${BAILIAN_WORKSPACE_ID}

defaults:
  provider: bailian

environments:
  dev:
    config:
      type: cloud
      networking:
        type: unrestricted

agents:
  assistant:
    description: "General-purpose coding assistant"
    model: qwen3.7-max
    instructions: |
      You are a coding assistant.
    environment: dev
    tools:
      builtin: [bash, read, glob, grep]

Secrets are referenced with ${VAR_NAME} and loaded from .env — they never live in the config itself. For the full walkthrough, see Getting started.

Installation

Install the CLI globally:

# with Bun
bun add -g @openagentpack/cli

# or with npm
npm install -g @openagentpack/cli

This provides the agents command. To run from source instead, see Contributing. Beta testers can install @openagentpack/cli@beta; see the release guide for version pinning and switching back to stable.

Provider support

Feature	Bailian	Qoder	Claude	Volcengine Ark
Environment	native	native	native	native
Vault	native	native	native	native
Skill	native	native	native	native
Agent	native	native	native	native
MCP Server	native	native	native	native
Memory Store	unsupported	native	unsupported	native
Multi-Agent	unsupported	unsupported	native	native
Deployment	emulated	emulated	native	emulated
Session	native	native	native	native

The full capability matrix and per-provider differences live in the Provider reference.

Documentation

Doc	What's inside
Getting started	Shortest path from install to a running session.
Configuration guide	Progressive tutorial from minimal to full config.
Configuration reference	Every agents.yaml field, typed and explained.
CLI reference	Every agents command, options, and behavior.
Provider reference	Capability matrix and per-provider configuration.
How it works	State, dependency graph, incremental diffing.
Examples	Runnable configs indexed by what you want to do.

The documentation index organizes the rest by reader goal: concepts, guides, reference, architecture, and contributing.

Examples

The examples/ directory has runnable configs for every provider, from a minimal agent to full-feature stacks (skills, MCP, vaults, multi-agent, deployments). Start with examples/bailian/basic/.

Using the SDK

Everything the CLI does is available programmatically from @openagentpack/sdk:

import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";

const config = await resolveProjectConfig({ configPath: "agents.yaml" });
const plan = await planProjectContext(config);
console.log(plan);

See the SDK reference for the public API surface.

WebUI

apps/webui is a Vite single-page app for browsing playbooks and driving agent sessions; apps/server exposes the SDK over an OpenAPI surface. Run both from the repo root:

bun install
bun run dev        # server + webui together

Or launch a packaged local UI with agents playground --provider <bailian|qoder|ark|claude>.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the dev setup, merge requirements, and how to add a new provider. All participants are expected to follow our Code of Conduct.

Use GitHub Discussions for questions and design proposals, and GitHub Issues for reproducible bugs and accepted work. Current priorities are tracked in the public roadmap.

Security

Found a vulnerability? Please follow the process in SECURITY.md — do not open a public issue.

License

Licensed under the Apache License, Version 2.0.