---
sidebar_position: 1
title: '@zibby/agent-workflow'
---

# @zibby/agent-workflow

[![npm](https://img.shields.io/npm/v/@zibby/agent-workflow.svg)](https://www.npmjs.com/package/@zibby/agent-workflow)
[![GitHub](https://img.shields.io/badge/github-ZibbyHQ%2Fagent--workflow-blue)](https://github.com/ZibbyHQ/agent-workflow)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ZibbyHQ/agent-workflow/blob/main/LICENSE)

The graph engine itself. Zero agent strategies, zero skills bundled — bring your own. This is the package you'd depend on if you want to embed the workflow runtime in your own app without the rest of the Zibby ecosystem.

```bash
npm install @zibby/agent-workflow
```

## What's in it

| Export | Purpose |
|---|---|
| `WorkflowGraph` | The graph builder. `addNode`, `addEdge`, `addConditionalEdges`, `setEntryPoint`, `run`. |
| `WorkflowAgent` | Base class your `graph.mjs` exports — has `buildGraph()`. |
| `Node` | Internal node class (rarely used directly). |
| `WorkflowState` | History-tracked state passed between nodes. |
| `AgentStrategy` | Base class for custom agent strategies. |
| `registerStrategy`, `listStrategies`, `getAgentStrategy`, `invokeAgent` | Strategy registry. |
| `registerSkill`, `getSkill`, `hasSkill`, `getAllSkills` | Skill registry. |
| `compileGraph` | Build a graph from a JSON config (the format Studio writes). |
| `ContextLoader` | Walks the spec dir for `CONTEXT.md` / `AGENTS.md` and merges into state. |
| `timeline`, `WORKFLOW_GRAPH_LOG_MARKER_PREFIX` | CLI progress UX + structured markers consumed by Studio. |

## Standalone usage

```js
import { WorkflowGraph, AgentStrategy, registerStrategy } from '@zibby/agent-workflow';
import { z } from 'zod';

class FakeAgent extends AgentStrategy {
  constructor() { super('fake', 'demo', 0); }
  canHandle() { return true; }
  async invoke(prompt, { schema }) {
    return { raw: 'ok', structured: schema.parse({ summary: 'hello' }) };
  }
}
registerStrategy(new FakeAgent());

const graph = new WorkflowGraph()
  .addNode('plan', {
    prompt: 'List 3 tasks for: {{input.goal}}',
    outputSchema: z.object({ summary: z.string() }),
    agent: 'fake',
  })
  .setEntryPoint('plan');

const { state } = await graph.run(null, {
  input: { goal: 'add dark mode' },
  agentType: 'fake',
});

console.log(state.plan.summary);   // → 'hello'
```

## What it is *not*

`@zibby/agent-workflow` is **just the engine**. It does not:

- Ship any agent strategies (no Claude/Cursor/Codex/Gemini implementations)
- Ship any skills (no Browser/Jira/GitHub MCP)
- Provide a CLI

For the batteries-included experience, use `@zibby/cli` + `@zibby/core` + `@zibby/skills`. For an embeddable engine, this package alone is enough.

## Public protocol surface (stable)

These constants are part of the public contract and consumed by Zibby Studio + tooling. They won't break across minor versions:

- `WORKFLOW_GRAPH_LOG_MARKER_PREFIX` (`__WORKFLOW_GRAPH_LOG__`)
- `STUDIO_STOP_REQUEST_FILE` (`.zibby-studio-stop`)
- `ZIBBY_RUN_SOURCE=studio` env trigger
- `stoppedByStudio: true` return key
- Marker payload `{ phase: 'node_begin' | 'node_end', node: string }`

## Source

- npm: [`@zibby/agent-workflow`](https://www.npmjs.com/package/@zibby/agent-workflow)
- GitHub (public, MIT): [ZibbyHQ/agent-workflow](https://github.com/ZibbyHQ/agent-workflow)
- Examples: [01-hello-world](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/01-hello-world) · [02-pipeline](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/02-pipeline) · [03-conditional-routing](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/03-conditional-routing) · [04-custom-agent](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/04-custom-agent) · [05-with-skills](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/05-with-skills)