Metadata-Version: 2.4
Name: agentork
Version: 0.1.0
Summary: Orchestration framework for multi-agent workflows via external commands
Project-URL: Homepage, https://github.com/agentork/agentork
Project-URL: Repository, https://github.com/agentork/agentork
Project-URL: Documentation, https://github.com/agentork/agentork#readme
Project-URL: Issues, https://github.com/agentork/agentork/issues
Author-email: xiaocong <180146906@qq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,orchestration,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph>=0.3
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <strong>AgentOrk</strong>
</p>

<p align="center">
  Orchestrate multi-agent workflows declaratively.
</p>

<p align="center">
  <a href="README.md"><strong>English</strong></a> ·
  <a href="README_zh.md">简体中文</a>
</p>

<p align="center">
  <a href="https://github.com/agentork/agentork/actions/workflows/ci.yml"><img src="https://github.com/agentork/agentork/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT"></a>
  <a href="https://pypi.org/project/agentork/"><img src="https://img.shields.io/pypi/v/agentork.svg" alt="PyPI"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> ·
  <a href="#how-it-works">How It Works</a> ·
  <a href="#features">Features</a> ·
  <a href="#usage">Usage</a> ·
  <a href="#documentation">Docs</a>
</p>

<br>

**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

```bash
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:

```bash
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):**

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

---

## How It Works

```text
  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](docs/en/architecture.md) · [Pattern starter YAMLs](tests/patterns/workflows/starter/) · [3×5 matrix tests](tests/patterns/README.md)

---

## 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:

```text
/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:

```yaml
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](examples/scripts/mock_agent.py)).

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

```bash
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](tests/patterns/workflows/starter/01-sequential.yaml)):

```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 `id`s** with **separate `agents` keys** even when the command is the same — see [02-parallel.yaml](tests/patterns/workflows/starter/02-parallel.yaml).

Full schema: [docs/en/yaml-reference.md](docs/en/yaml-reference.md).

### Workflow templates

Starters: **docs sit next to each YAML** in [tests/patterns/workflows/starter/](tests/patterns/workflows/starter/).

| YAML | Doc |
|------|-----|
| [01-sequential.yaml](tests/patterns/workflows/starter/01-sequential.yaml) | [01-sequential.md](tests/patterns/workflows/starter/01-sequential.md) |
| [02-parallel.yaml](tests/patterns/workflows/starter/02-parallel.yaml) | [02-parallel.md](tests/patterns/workflows/starter/02-parallel.md) |
| [03-loop.yaml](tests/patterns/workflows/starter/03-loop.yaml) | [03-loop.md](tests/patterns/workflows/starter/03-loop.md) |
| [04-composite.yaml](tests/patterns/workflows/starter/04-composite.yaml) | [04-composite.md](tests/patterns/workflows/starter/04-composite.md) |

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

```bash
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

```bash
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](docs/en/api.md).

### Claude Code plugin

```text
/plugin marketplace add <your-org>/AgentOrk
```

See [`claude-plugin/`](claude-plugin/) and [docs/en/plugin.md](docs/en/plugin.md).

---

## Project structure

```text
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](examples/scripts/mock_agent.py)).

---

## Documentation

| English | 中文 |
|---------|------|
| [Architecture](docs/en/architecture.md) | [架构](docs/zh/architecture.md) |
| [YAML reference](docs/en/yaml-reference.md) | [YAML 参考](docs/zh/yaml-reference.md) |
| [API](docs/en/api.md) | — |
| [Plugin](docs/en/plugin.md) | — |
| [Monitor](docs/en/monitor.md) | [监控](docs/zh/monitor.md) |
| [Pattern tests](tests/patterns/README.md) | [AI pipeline demo](tests/ai-pipeline/README.md) |
| [Workflow template index](docs/en/workflow-templates.md) | [模板索引](docs/zh/workflow-templates.md) |
| [Starter templates](tests/patterns/workflows/starter/README.md) | [starter 目录](tests/patterns/workflows/starter/) |

---

## Contributing

```bash
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](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). Changelog: [CHANGELOG.md](CHANGELOG.md).

---

## License

MIT — see [LICENSE](LICENSE).

<p align="center">
  <sub>pip install agentork · declarative workflows · orchestrate multi-agent runs</sub>
</p>
