agentbundle

Agent Bundle

[English](README.md) | [简体中文](README.zh-CN.md)

Agent Bundle packages an agent's instructions, configuration, skills, plugins, and entry points into a directory with a bundle.yaml manifest. The manifest identifies the target agent harness: the runtime that loads and executes the agent.

This project provides the agent-bundle CLI and agent-bundle-core TypeScript SDK to validate, install, track, and uninstall bundles through harness-specific adapters.

Why use it?

• Deliver an agent as a versioned set of resources with an explicit runtime contract.
• Validate resources and compute a content digest before installation.
• Install through one interface while respecting each harness's resource layout.
• Track installations, reuse matching content, and remove installed resources.
• Trial-install in an isolated home before adopting a bundle.

Bundles target a specific harness; adapters do not translate agents between runtimes. Install the runtime and supply its credentials separately. Installation prepares the agent; launch the harness afterward to execute tasks.

Supported harnesses

| Harness | Manifest kind | Adapter behavior | Details |

| --- | --- | --- | --- |

| DSH | dsh-agent-bundle | Installs native plugins and profile settings. | [Format guide](./docs/bundle-formats.md#dsh) |

| Dify | dify-agent-bundle | Imports workflow DSL through the Dify Console API; requires a running service and Console credentials. | [Format guide](./docs/bundle-formats.md#dify) |

| Pi | pi-agent-bundle | Maps instructions, skills, extensions, and settings. Use harness.name: pi. | [Format guide](./docs/bundle-formats.md#pi) |

| Hermes | hermes-agent-bundle | Copies and enables directory plugins and writes model selection. | [Format guide](./docs/bundle-formats.md#hermes) |

| deepagents | deepagents-agent-bundle | Creates an isolated Python environment and installs bundle packages in editable mode; requires uv or Python ≥ 3.11. | [Format guide](./docs/bundle-formats.md#deepagents) |

| jiuwenswarm | jiuwenswarm-agent-bundle | Materializes templates, skills, packages, and configuration in an isolated data root. | [Format guide](./docs/bundle-formats.md#jiuwenswarm) |

Get started

Requires Node.js ≥ 22 and pnpm (version pinned in package.json). From the repository root:

pnpm install
pnpm build

cd packages/cli
pnpm add -g .

Obtain a bundle for a supported harness. Required resource fields and files depend on its kind.

# Static validation without installation
agent-bundle verify ./my-bundle --level standard

# Validate, trial-install into an isolated home, then uninstall
agent-bundle verify ./my-bundle

# Install; keep the returned installation id and launch information
agent-bundle install ./my-bundle
agent-bundle list

# Remove an installation
agent-bundle uninstall --id 

Launch the agent with its harness using the installation's launch information. Model credentials and provider setup follow that harness's conventions.

Options and installation behavior

• CLI installation defaults to native mode for DSH, Pi, and Hermes, reusing the harness home. --home selects an isolated home; uninstall removes that directory in full. Use a dedicated directory.
• Native uninstall removes bundle-owned resources. Dify also creates and removes remote resources through its API.
• install --profile selects a DSH or Pi native profile; install --force reinstalls matching content.
• verify --expect-digest sha256: rejects unexpected content. minimal and standard levels perform static checks; the CLI default install level requires the runtime/service for a trial installation.
• --json produces machine-readable output. Exit codes: 0 success, 1 operation failure, 2 usage error.
• AGENT_BUNDLE_REGISTRY overrides ~/.agent-bundle/installations.json.

Runtime overrides: DSH_BIN / DSH_CHECKOUT, PI_BIN / PI_CHECKOUT, HERMES_BIN, UV_BIN / PYTHON_BIN, JIUWENSWARM_BIN / JIUWENSWARM_CHECKOUT. Dify accepts DIFY_BASE with DIFY_EMAIL / DIFY_PASSWORD or DIFY_ADMIN_API_KEY.

TypeScript SDK

import { createBundleSdk } from 'agent-bundle-core'

const sdk = createBundleSdk()
const info = await sdk.inspect('./my-bundle')
const verified = await sdk.verify('./my-bundle')
console.log(info, verified.digest)

The SDK also exposes pack, install, activate, load, and uninstall. SDK verification defaults to static standard checks. Installation and runtime operations require the appropriate injected process functions (runDsh, runHermes, or runPython) where used; core does not spawn processes. SDK installation defaults can differ from CLI defaults; explicitly select mode: 'native' where supported to use an existing harness home.

Development

pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e