agentork 0.1.0

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

Pattern	When to use
sequential	Linear pipeline — A → B → C
parallel	Fan-out / fan-in — one node to many workers, then merge
evaluator_optimizer	Draft + review loop until quality gate passes
composite	Mix sequential, parallel, and loops with explicit edges

Collaboration patterns

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

Pattern	Typical layout
generator_verifier	Generate → verify → retry
orchestrator_subagent	Orchestrator emits tasks → parallel subagents
agent_teams	Lead + worker pool
message_bus	Publish / subscribe style steps
shared_state	Agents read/write shared files under workspace

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

---

Features

Feature	Details
YAML workflows	Nodes, edges, I/O sources, output targets, parallelism
Multi-agent	Bring your own scripts or tools as node commands
3 workflow modes	Sequential, parallel, evaluator-optimizer (+ composite)
5 collaboration modes	Generator-verifier, orchestrator-subagent, teams, bus, shared state
Parallel dispatch	parallelism.limit with max or fixed batching
File run state	manifest.json, per-node input.json / output.json, logs
Event stream	events.jsonl for monitor UI and debugging
CLI	validate, run, serve, dashboard
HTTP API	Start/cancel runs, optional AGENTORK_API_KEY
Monitor UI	Live run timeline at /monitor
Claude Code plugin	Skill to drive agentork from the editor
Examples	Mock agents, combined pipeline, ai-pipeline integration demo

---

Usage

CLI reference

Command	Description
agentork validate -c workflow.yaml	Validate YAML against schema
agentork run -c workflow.yaml	Execute workflow
agentork run -c workflow.yaml --inputs '{"workspace":"/tmp/ws"}'	Pass initial state / workspace
agentork run -c workflow.yaml --dashboard	Run and open monitor
agentork serve --port 8080	HTTP API + embedded monitor
agentork dashboard	Monitor-only server (default port 7979)

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

Field	Meaning
name	Workflow name (required)
workflow.pattern	How edges are built: sequential, parallel, evaluator_optimizer, composite
collaboration.pattern	Collaboration semantics label (e.g. orchestrator_subagent, generator_verifier)

graph — execution graph

Field	Meaning
graph	Block defining steps and (optionally) edges
nodes	List of steps to run
nodes[].id	Unique node ID — used for edges, logs, AGENTORK_NODE_ID (may differ from agent)
nodes[].agent	Key into agents: — which command config to run
nodes[].role	Optional role label (orchestrator, subagent, generator, …)
graph.edges	Optional from / to (node id or list). Omitted in sequential → auto chain A → B → C

agents — how each step runs

Field	Meaning
agents	Map of agent id → subprocess settings
agents.<id>	Must match nodes[].agent (e.g. worker)
command	argv list, e.g. ["python3", "scripts/my_agent.py"]
cwd	Working directory for the subprocess; "." = directory where you run agentork
timeout_sec	Max seconds per invocation (default 300); -1 = no timeout

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/.

YAML	Doc
01-sequential.yaml	01-sequential.md
02-parallel.yaml	02-parallel.md
03-loop.yaml	03-loop.md
04-composite.yaml	04-composite.md

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

Method	Path	Description
POST	/api/v1/runs	Start a run
GET	/api/v1/runs/{run_id}	Status
POST	/api/v1/runs/{run_id}/complete	Mark complete
POST	/api/v1/runs/{run_id}/cancel	Cancel

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

Variable	Description	Default
AGENTORK_API_KEY	API auth for agentork serve	—
AGENTORK_AUTH_DISABLED	Set 1 to disable API key check	off
AGENTORK_MONITOR_PORT	Port for agentork dashboard	7979
AGENTORK_RUNS_ROOT	Monitor scans this directory for runs	.agentork/runs
AGENTORK_MONITOR_NO_BROWSER	Set 1 to skip opening browser	off
AGENTORK_RUN_ID	Set by runner — current run id	—
AGENTORK_NODE_ID	Set by runner — current node id	—
AGENTORK_INPUT_FILE	JSON input path for agent subprocess	—
AGENTORK_TASK_ID	Parallel sub-task id when applicable	—

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

---

Documentation

English	中文
Architecture	架构
YAML reference	YAML 参考
API	—
Plugin	—
Monitor	监控
Pattern tests	AI pipeline demo
Workflow template index	模板索引
Starter templates	starter 目录

---

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}