agentork

AgentOrk

Orchestrate multi-agent workflows declaratively.

English · 简体中文

Quick Start · How It Works · Features · Usage · Docs

AgentOrk is an orchestration framework for multi-agent workflows. Wire external commands (Python scripts, Claude Code CLI, Cursor CLI, shell tools, remote wrappers) into declarative workflows. The framework handles graph execution, I/O routing, parallelism limits, and run persistence.

---

Quick Start

pip install agentork                    # or: pip install -e ".[dev]" from a clone
agentork validate -c tests/patterns/workflows/starter/01-sequential.yaml
agentork run -c tests/patterns/workflows/starter/01-sequential.yaml \
  --inputs '{"workspace": "/tmp/agentork-demo"}'

Open the monitor (optional) — same workflow as above:

agentork run -c tests/patterns/workflows/starter/01-sequential.yaml \
  --inputs '{"workspace": "/tmp/agentork-demo"}' \
  --dashboard
# or after any run: agentork dashboard  →  http://127.0.0.1:7979/monitor/

Requires Python 3.10+. Run artifacts (framework state) live under .agentork/runs/{run_id}/. Your agents write business output wherever workspace points in --inputs.

From source (contributors):

git clone https://github.com/agentork/agentork.git
cd agentork
pip install -e ".[dev]"
pytest -v

---

How It Works

  workflow.yaml          agents: external commands (scripts, CLIs)
        │                         │
        ▼                         ▼
  ┌─────────────┐    subprocess    ┌──────────────┐
  │  Workflow   │ ───────────────► │  AgentOrk    │
  │  engine     │ ◄─────────────── │  run state   │
  └─────────────┘   JSON in/out    └──────────────┘
        │
        ▼
  .agentork/runs/{run_id}/   manifest, logs, node I/O

1. You define nodes (steps) and edges (order) in YAML, plus an agents map (command, cwd, timeout).
2. AgentOrk executes the workflow graph, resolves inputs from upstream / state / files, and runs each node as a subprocess.
3. Stdout JSON becomes node output; optional parallelism fans out over a tasks list (orchestrator pattern).
4. loops / evaluator_optimizer connect generator ↔ verifier until a pass condition or max iterations.

Workflow patterns

Collaboration patterns

Metadata on nodes (role) and top-level collaboration.pattern document intent. Complex topologies use explicit graph.edges in composite workflows.

Learn more: Architecture · Pattern starter YAMLs · 3×5 matrix tests

---

Features

---

Usage

CLI reference

Use in your project

After pip install agentork, keep the workflow in your repo (not inside the AgentOrk package). A typical layout:

/path/to/my-project/
├── agentork.yaml
├── scripts/
│   └── my_agent.py
└── .agentork/runs/          # created on first run (add to .gitignore)

agentork.yaml at the project root:

name: my-project
workflow:
  pattern: sequential
collaboration:
  pattern: orchestrator_subagent

graph:
  nodes:
    - {id: extract, agent: extract}
    - {id: validate, agent: validate}
    - {id: store, agent: store}

agents:
  extract:
    command: ["python3", "scripts/extract.py"]
    cwd: "."
    timeout_sec: 300
  validate:
    command: ["python3", "scripts/validate.py"]
    cwd: "."
    timeout_sec: 300
  store:
    command: ["python3", "scripts/store.py"]
    cwd: "."
    timeout_sec: 300

Each step uses its own agents entry (sequential pipelines usually map one node → one command). Scripts should read AGENTORK_INPUT_FILE and print JSON to stdout (see examples/scripts/mock_agent.py).

Run from the project root (cwd: "." is relative to where you invoke agentork):

cd /path/to/my-project

agentork validate -c agentork.yaml

agentork run -c agentork.yaml \
  --inputs '{"workspace": "/path/to/my-project"}'

Framework state is written under ./.agentork/runs/{run_id}/ in that directory; your agents write business output under workspace. For another project, use a different directory and its own agentork.yaml.

YAML configuration

Minimal files need name, workflow.pattern, collaboration.pattern, graph, and agents. Optional: version, state, graph.edges, input / output, parallelism, loops, evaluator_optimizer.

Top-level

graph — execution graph

agents — how each step runs

The subprocess reads JSON from AGENTORK_INPUT_FILE and should print JSON on stdout. workspace / source_dir from --inputs are injected into node input when configured.

Example (matches 01-sequential.yaml):

graph:
  nodes:
    - {id: extract, agent: extract}     # node id → agents.extract
    - {id: validate, agent: validate}
    - {id: store, agent: store}

agents:
  extract:
    command: ["python3", "scripts/extract.py"]
    cwd: "."
  validate:
    command: ["python3", "scripts/validate.py"]
    cwd: "."
  store:
    command: ["python3", "scripts/store.py"]
    cwd: "."

Parallel workflows may use different node ids with separate agents keys even when the command is the same — see 02-parallel.yaml.

Full schema: docs/en/yaml-reference.md.

Workflow templates

Starters: docs sit next to each YAML in tests/patterns/workflows/starter/.

More: examples/ · docs/zh/workflow-templates.md (index)

agentork run -c tests/patterns/workflows/starter/01-sequential.yaml \
  --inputs '{"workspace": "/tmp/agentork-demo"}'

workspace and source_dir from --inputs are injected into nodes automatically when configured.

HTTP API

export AGENTORK_AUTH_DISABLED=1   # dev only; or: export AGENTORK_API_KEY=your-secret
agentork serve --port 8080

See docs/en/api.md.

Claude Code plugin

/plugin marketplace add <your-org>/AgentOrk

See claude-plugin/ and docs/en/plugin.md.

---

Project structure

agentork/
├── src/agentork/           # Framework (config, graph, engine, api, monitor)
├── examples/               # Sample workflow YAML + mock scripts
├── tests/                  # Pytest + pattern matrix + starter YAMLs
├── docs/en/ · docs/zh/     # Documentation
├── claude-plugin/          # Claude Code marketplace plugin
├── pyproject.toml
├── README.md · README_zh.md
└── LICENSE

---

Configuration

Environment variables

Agent subprocesses should read AGENTORK_INPUT_FILE and print JSON to stdout (see examples/scripts/mock_agent.py).

---

Documentation

---

Contributing

git clone https://github.com/agentork/agentork.git
cd agentork
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
ruff check src tests

See CONTRIBUTING.md and SECURITY.md. Changelog: CHANGELOG.md.

---

License

MIT — see LICENSE.

_{pip install agentork · declarative workflows · orchestrate multi-agent runs}