About glink-engine

Zero-dependency multi-agent workflow orchestration engine. YAML pipelines, shared event bus, auto-recovery, real-time dashboard.

g

Published by

garyqlin

Visit View Profile

README.md

View on GitHub

🚀 Glink — Multi-Agent Workflow Orchestration Engine

Glink is a lightweight, event-bus-driven workflow orchestration engine designed for AI agent teams. Think of it as a conductor for your AI agents — each agent plays its part, and Glink ensures the symphony runs on time.

Why Glink?

Most AI agents work in isolation. Glink breaks that pattern with a Main Bus shared-blackboard architecture — agents write results to a common bus, and the next agent reads, processes, and writes back. No direct agent-to-agent coupling, no single point of failure.

┌──────────────────────────────────────────────────┐
│                   Glink Engine                    │
│                                                   │
│   Agent A ──► Main Bus ──► Agent B ──► Agent C   │
│                                                   │
│   ┌──────────── Shared Checkpoint ────────────┐  │
│   │  Parallel / Sequential / Conditional Steps │  │
│   └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Quick Start

# Clone
git clone https://github.com/opprime/glink
cd glink

# Start in serve-only mode (API only, no workflow execution)
python3 glink-daemon.py my-project --serve

# In another terminal, submit a workflow
curl -X POST http://127.0.0.1:8426/workflow/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "project": "hello-world",
    "steps": [
      {"step": 1, "agent": "agent-a", "task": "Say hello"}
    ]
  }'

# Check workflow status
curl http://127.0.0.1:8426/status/project

Architecture

Component	Role
Main Bus	Append-only JSONL event log. All agents read/write here
Daemon API	HTTP server — submit workflows, check status, read events
Core Engine	Step executor — sequential, parallel, review modes
Checkpoint	Crash recovery — track step progress with SHA256 checksums
Reporter	Optional notification — console, or webhook (e.g. Feishu)

Features

✅ Bus-driven orchestration — event bus as shared state, no direct agent coupling
✅ Sequential & parallel execution — DAG-based step resolution
✅ Crash recovery — SHA256-verified checkpoints, auto-restart from last completed step
✅ Path traversal protection — _safe_project_path() prevents directory escape
✅ Concurrency safety — LOCK_SH/LOCK_EX on checkpoint files, ThreadingHTTPServer
✅ Token authentication — Bearer token via GLINK_API_TOKEN env var
✅ Task enrichment — inject context from bus before dispatching to agents
✅ Reporter abstraction — console, feishu webhook, or custom reporter plugin

Configuration

See glink-config.yaml for all options:

server:
  host: "127.0.0.1"
  port: 8426

bus:
  dir: "bus"
  retention_days: 30

reporting:
  - type: console

Workflow Definition

Workflows are YAML files specifying agent steps. Example:

name: my-workflow
steps:
  - step: 1
    agent: search-agent
    task: "Search for top-rated coffee shops in Shanghai"
  - step: 2
    agent: code-agent
    task: "Convert search results to JSON"
  - step: 3
    agent: frontend-agent
    task: "Build an HTML card page from JSON"
    after: [1]

API Endpoints

Method	Path	Description
GET	`/health`	Health check
POST	`/workflow/run`	Submit a workflow for execution
GET	`/status`	Engine status
GET	`/status/project`	Latest completed project status
GET	`/projects`	List all known project names
POST	`/write`	Write an event to the bus
GET	`/events?project=X`	Stream events for a project

Security

Token auth: Set GLINK_API_TOKEN env var. All endpoints except /health require Authorization: Bearer <token>.
Path sanitization: All file paths are sanitized against directory traversal.
Local binding: Defaults to 127.0.0.1 — only accessible locally.
Checkpoint integrity: SHA256 checksums detect corrupted/incomplete writes.
Safe file operations: Atomic write-then-rename pattern, strict lock management.

Development

# Install dev dependencies
pip install pytest

# Run tests
python3 -m pytest tests/

# Lint
pip install ruff
ruff check daemon/ bus/

License

MIT

Built for agents, by agents. 🤖

glink-engine