Capsule
GitHub
Open-Source · Python 3.12

Agents. Packaged.
Tested. Compiled.

Capsule is the packaging, testing, and compiler layer for AI agent workflows. Define your workflow once as a capsule.yaml, run it locally, and compile it to supported runtimes.

Get Started Star on GitHub
capsule.yaml → runtime
YAML
capsule.yaml
runtime
SCAN
RUN
TEST
capsule scan output 
$ capsule scan
✓ Manifest loaded: my_agent/capsule.yaml
✓ Schema valid
✓ Models declared: deterministic-dev
✓ Tools scanned: policy_search, draft_reply
⚠ draft_reply declares write_draft
✓ Scan completed
01

Define

Write a single capsule.yaml that describes your agent: models, tools, prompts, and I/O schema. One file. Infinite clarity.

02

Scan

Run capsule scan to validate your manifest, detect insecure tools, and verify model declarations before anything executes.

03

Compile

Export the same workflow into supported target projects. LangGraph runs end-to-end locally today; CrewAI and OpenAI Agents exports are generated and import-tested.

Everything an agent needs.

Not a framework. Not an orchestrator. Capsule is the spec, validator, test runner, and adapter layer around your agent stack.

Declarative Schema

The capsule.yaml is your agent workflow contract. Models, tools, prompts, schemas, permissions, and routing live as code that can be reviewed and tested.

Static Security Scan

Run capsule scan before any agent executes. It validates the manifest, flags unsafe tool patterns, and checks model and tool references.

Workflow Testing

Write .yaml test cases with mocked tool outputs. Run them with capsule test to replay flows deterministically — no LLM calls needed.

MCP Declarations

Declare MCP tool boundaries directly in your capsule. Current support is declaration-only with mocked local tests; live MCP orchestration is on the roadmap.

Multi-Agent Support

Compose agents into pipelines. A capsule can declare sub-agents as dependencies, and Capsule routes messages between them with full type-safe I/O.

Adapter-Based Exports

Capsule currently compiles to LangGraph, CrewAI Flows, and OpenAI Agents SDK. Additional adapters such as Haystack are planned, not shipped yet.

What works today.

Capsule is early, so the public contract is explicit. Use this table to know what is runnable now and what still needs credentials or a future adapter.

Target Status Expected behavior
Capsule local runtime Runnable validate, scan, test, run, build, and verify-bundle work on the starter workflow.
LangGraph Runnable Generated LangGraph output runs end-to-end with local Python tools and no LLM API key for the starter workflow.
CrewAI Flows Generated Generated project imports against real CrewAI on Python 3.12. Full native execution requires model/provider credentials.
OpenAI Agents SDK Generated Generated project imports against the real SDK. Full native execution requires OPENAI_API_KEY or another configured provider.
Haystack Planned No compiler adapter yet. capsule compile --target haystack is expected to return Unsupported target.

The capsule.yaml Spec

Click any key to understand exactly what it does, what it validates, and why it matters.

my-agent/capsule.yaml
name: refund-support-agent
version: 0.1.0
description: >
  Processes customer refund requests
  and determines eligibility.

models:
  default:
    provider: local
    model: deterministic-dev

agents:
  triage:
    prompt: agents/triage.md
    model: default
    tools:
      - policy_search

tools:
  policy_search:
    type: python
    entrypoint: tools/policy_search.py:search_policy
    permission: read

input_schema:
  type: object
  properties:
    order_id:
      type: string

workflow:
  start: triage
  steps:
    - id: triage
      type: agent
      agent: triage
Field Required

name

A unique slug identifier for this agent capsule. Used in CLI output, logs, and when referencing this agent as a sub-agent from another capsule.

Validation

  • Must be a non-empty string
  • No spaces — use hyphens or underscores
  • Must be unique within your project

Impact

Shown in all CLI output, scan reports, and used as the registry key when agents reference sub-agents. A bad name causes routing failures in pipelines.

💡 Tip Match the name to your directory name for maximum clarity. E.g., folder refund-agent/ → name: refund-agent.

Scan before you run.

capsule scan validates every declaration statically. Catch misconfigurations before they reach production.

capsule scan — security report

Up in 60 seconds.

From zero to a running, scanned, compiled starter workflow.

Shell 
$ pip install git+https://github.com/vindepemarte/Capsule.git

# Verify installation
$ capsule --help
Package, test, and compile portable AI agent workflows.
capsule.yaml 
# my-agent/capsule.yaml

$ capsule init refund-support-agent
$ cd refund-support-agent
# The starter includes capsule.yaml, prompts, tools, examples, and tests.
Shell 
# Validate and scan your capsule
$ capsule validate
Validation passed.

$ capsule scan
warning security.risky_permission: draft_reply declares write_draft

# Run your agent
$ capsule run --input examples/refund-request.json --allow-all
trace path: triage -> responder

# Run tests
$ capsule test
All tests passed.
Shell 
# Strongest no-key framework proof today
$ capsule compile --target langgraph
$ uv run --with langgraph python dist/langgraph/main.py examples/refund-request.json
"last_node": "responder"

# Generated/import-tested targets; full runs need model credentials
$ capsule compile --target crewai
$ capsule compile --target openai-agents