@zibby/agent-workflow

Deutsch | Español | français | 日本語 | 한국어 | Português | Русский | 中文

📖 Full docs: docs.zibby.app · Get Started · Concepts · Designing agents · Cloud

The cloud pipeline for Claude Code, Codex, and Gemini. Compose them into structured workflows with Zod-validated handoff between nodes. Vendor-neutral, JavaScript-first, runs locally or in our cloud.

                ┌──────────┐    ┌──────────┐    ┌──────────┐
   trigger  →   │  plan    │ →  │ implement│ →  │  verify  │   →  result
                │ (claude) │    │ (codex)  │    │ (gemini) │
                └──────────┘    └──────────┘    └──────────┘
                     │               │               │
                  Zod out         Zod out         Zod out

Each node hands off to a complete agent. The agent does its own tool calls, file edits, and multi-turn reasoning. Your graph defines what agent runs when, what schema it has to return, and what state flows between them.

Mix and match agents per node — Claude for planning, Codex for implementation, Gemini for verification. Or stick with one. Your call:

graph
  .addNode('plan',      { prompt, outputSchema: Plan,   agent: 'claude' })
  .addNode('implement', { prompt, outputSchema: Diff,   agent: 'codex'  })
  .addNode('verify',    { prompt, outputSchema: Result, agent: 'gemini' });

Each agent reads its own credential env var (ANTHROPIC_API_KEY, OPENAI_API_KEY). In Zibby Cloud you can set those per-workflow — different keys per pipeline, no global state — see Per-workflow env vars. Each node runs on the model the run config names for it (config: { models: { node_id: 'claude-opus-4.6', default: '…' } }); a node never borrows another node's model.

---

⚡ Try it in 60 seconds

npm install @zibby/agent-workflow zod

Save this as index.mjs and run node index.mjs. It uses a stand-in agent with canned answers, so it runs offline with no API key:

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

// 1. Bring your own agent. A real one calls Claude Code, Codex, an API…
//    This one returns canned output per node so you can run it offline.
class EchoAgent extends AgentStrategy {
  constructor() { super('echo', 'Canned answers for the quickstart'); }
  canHandle() { return true; }
  async invoke(prompt, { nodeName }) {
    const answers = {
      plan:   { tasks: ['Add a theme setting', 'Add the toggle', 'Test both themes'] },
      finish: { summary: `Echo of: ${prompt}` },
    };
    const structured = answers[nodeName];
    return { raw: JSON.stringify(structured), structured };
  }
}
registerStrategy(new EchoAgent());

// 2. Declare the graph: each node has a prompt and a Zod output schema.
const Plan = z.object({ tasks: z.array(z.string()) });
const Done = z.object({ summary: z.string() });

const graph = new Graph()
  .addNode('plan',   { prompt: 'List 3 tasks for: {{goal}}', outputSchema: Plan })
  .addNode('finish', {
    prompt: (state) => `Summarise: ${state.plan.tasks.join(', ')}`,
    outputSchema: Done,
  })
  .addEdge('plan', 'finish')
  .setEntryPoint('plan');

// 3. Run it. Each node's output lands in state under the node's name.
const { state } = await graph.run(null, {
  goal: 'add a dark-mode toggle',
  agentType: 'echo',
  config: { models: { default: 'echo-1' } },  // a model per node id, or one default
});

console.log(state.plan.tasks);      // [ 'Add a theme setting', 'Add the toggle', 'Test both themes' ]
console.log(state.finish.summary);  // Echo of: Summarise: Add a theme setting, …

To use a real coding agent, replace EchoAgent with an AgentStrategy whose invoke calls it and returns { raw, structured } — see examples/04-custom-agent. Every run writes a session folder under .zibby/output/sessions/<id>/ that you can inspect afterwards.

See examples/ for runnable demos of each pattern.

---

🚀 Self-hosted Zibby (single VM)

Run the full Zibby platform — control plane + agents + marketplace — on your own box:

curl -fsSL https://dl.zibby.app/selfhosted/latest/install.sh | bash

Requirements: Docker + ~8 GB RAM. The installer downloads the release bundle, docker loads the images locally (no registry login needed), generates secrets, brings the stack up, and prints your dashboard URL + access token. Free tier: up to 10 deployed agents.

---

What this is not

	What it does	Why this is different
LangGraph	Python-first graph runtime over LangChain — nodes are LangChain agents or LLM calls, state is shared via the graph.	Our nodes hand off to external coding-agent CLIs (Claude Code, OpenAI Codex, Gemini CLI) — independent processes that own their own tool use, multi-turn loops, and file edits. JS-first, no Python interop, no LangChain assembly.
n8n / Zapier	Visual workflow editor — wire SaaS APIs together.	Code-first, no UI. Built around composing coding-agent CLIs against your repo, not connecting SaaS APIs.
CrewAI / AutoGen	Multi-agent role-play — agents converse to solve a task.	No agent debate. Each node is a discrete, schema-validated invocation. Deterministic edges, retry-friendly.

If you want to compose Claude Code + Codex + Gemini into one pipeline with structured handoff between them — JS, no Python, no LangChain — this is that.

---

Concepts

Primitive	What it does
Graph	The DAG. addNode, addEdge, addConditionalEdges, setEntryPoint.
Fan-out	Call addEdge more than once from the same node and every branch runs, each carrying on through its own children. Branches run sequentially in declaration order (depth-first: a branch finishes before the next starts). Where branches converge, the shared node waits for all of them and runs once — see Fan-out below.
Node	One agent invocation. Config: prompt, outputSchema (Zod), optional agent, retries, skills.
Retries	retries: N = N retries on ANY failure (N+1 attempts), no delay — declared per node. On top of that, a failure the engine can POSITIVELY identify as a transient provider failure (a dead stream, a 429, an upstream 5xx) buys up to AGENT_TRANSIENT_RETRIES extra attempts (default 2) with exponential backoff (AGENT_TRANSIENT_BACKOFF_MS, default 5000, 0 = no wait). One loop, one decider — classifyFailure in failure-class.ts. A failure it cannot positively identify is DETERMINISTIC and is never retried, because retrying a bug is an infinite loop that burns money.
Sub-graph node	addNode(name, { workflow: 'other-name', ... }) — dispatches another deployed workflow as a child. Sync (poll + merge) or async (async: true, fire-and-forget). See Sub-graphs below.
AgentStrategy	Abstract base. Implement canHandle(ctx) and invoke(prompt, opts).
registerStrategy()	Tells the engine what agents are available. Selected by node agent field → config.agents[name] → state.agentType.
WorkflowState	History-tracked state passed between nodes. / / / .

State flows automatically: when node plan completes with output { tasks: [...] }, that lands at state.plan.tasks and downstream nodes see it.

---

Fan-out

One node, several branches, each with its own children:

const graph = new Graph()
  .addNode('gather', { prompt: 'Collect the diff', outputSchema: Diff })
  .addNode('security', { prompt: 'Security review',    outputSchema: Findings })
  .addNode('perf',     { prompt: 'Performance review', outputSchema: Findings })
  .addNode('triage',   { prompt: 'Rank the findings',  outputSchema: Findings })
  .addNode('report',   { prompt: 'Write it up',        outputSchema: Report })
  .addEdge('gather', 'security')   // branch 1
  .addEdge('gather', 'perf')       // branch 2
  .addEdge('perf', 'triage')       //   …with its own child
  .addEdge('security', 'report')   // both branches converge
  .addEdge('triage', 'report')
  .setEntryPoint('gather');

The contract:

• Every branch runs. Declaring a second edge from a node used to replace the first; now it adds one.
• Sequentially, depth-first, in declaration order — branch 1 runs all the way through its children, then branch 2. Deliberately not concurrent: the engine binds "the node running right now" to shared state (_currentNodeTools), to the timeline's single current node, and to its stdout interception, so two nodes at once would read each other's tools and interleave each other's logs. Sequential branches need none of that. For genuine parallelism, dispatch each branch as a sub-graph — separate processes, no shared state.
• A join runs once. A node several branches converge on waits for all of them, then runs a single time with every branch's output already in state (state.security, state.triage). It re-arms if a loop drives the fan-out again.
• Conditional edges are unchanged — addConditionalEdges still picks exactly one path. A join is defined over the unconditional edges a fan-out creates; a conditional arrival schedules its target immediately, as it always has.
• A node routes either unconditionally or conditionally, not both. Mixing them on one node warns and keeps the last declaration.

---

Sub-graphs

A sub-graph node dispatches another deployed workflow as a child of the current one. Useful when a step is large enough to deserve its own state schema, its own version, and its own activity-tab history — but you want a parent to call it as part of a larger flow.

One extra field on the existing node config:

g.addNode('audit', { workflow: 'deep-audit' });

That's the entire feature surface. No new imports, no UUID in user code, no separate class. The engine recognizes workflow: and turns the node into a sub-graph dispatcher.

Sync vs async is a single flag:

g.addNode('audit',  { workflow: 'deep-audit' });                   // sync — parent blocks until child done
g.addNode('notify', { workflow: 'slack-notifier', async: true });  // fire-and-forget

State plumbing — each workflow has its own schema; the parent transforms parent state into child input and (optionally) extracts what it needs back out:

g.addNode('audit', {
  workflow: 'deep-audit',
  input:  (state) => ({ ticketId: state.ticketId }),
  output: 'auditResult.score',          // dot-path on child finalState
  // OR: output: (childState) => ({ score: childState.auditResult.score,
  //                                label: childState.auditResult.label }),
  retries: 3,                           // retry whole dispatch on transient failure
  timeoutMs: 5 * 60 * 1000,             // give up after 5min (sync mode only)
});

When a custom fan-out node also needs to persist an exact reference to the child execution, the direct dispatcher can return identity with the same projected value:

const { executionId, output } = await dispatchSubgraph('deep-audit', {
  input: { ticketId },
  output: 'auditResult',
  includeExecutionMetadata: true,
});

This is synchronous-only metadata; async dispatch already returns jobId.

Errors are typed so parents can branch:

err.code	When
SUBGRAPH_INVALID_INPUT	Parent's input: didn't satisfy child's stateSchema — server 400'd before any Fargate spawn
SUBGRAPH_QUOTA_EXCEEDED	Account over its execution cap; sub-graph runs count separately
SUBGRAPH_TRIGGER_FAILED	Any other dispatch failure

Same /trigger endpoint as user-initiated runs. The engine POSTs to /projects/<id>/workflows/<child-name>/trigger with parentExecutionId set. The server's input gate, quota check, and execution accounting all apply identically — a parent that fans out 10 children consumes 11 executions.

Full reference: docs.zibby.app/concepts/sub-graphs

---

Examples

	Shows
01-hello-world	Smallest possible graph — one node, one fake agent.
02-pipeline	Three nodes with typed handoff — state.plan.tasks flows into the next node.
03-conditional-routing	Branch on state with addConditionalEdges.
04-custom-agent	Bring your own AgentStrategy — calls OpenAI directly.
05-with-skills	Register an MCP-style skill, scope it to a node.

Run any of them:

cd examples/01-hello-world
npm install
node index.js

Examples 01–03 and 05 use a fake agent — no API key required.

---

Why graph-of-agents

Real coding agents (Claude Code, OpenAI Codex, Gemini CLI) are themselves capable runtimes — they edit files, run shells, call MCP tools, handle multi-turn. But on their own they have no memory across runs and no way to verify their own output.

A graph gives you:

• Structured handoff — node A returns a typed object, node B reads state.A. No prompt-stuffing, no parser bugs.
• Retries scoped to a node — bad output? rerun just that step.
• Conditional routing — addConditionalEdges for branch-on-state.
• Skill scoping — node A gets browser tools; node B gets git tools; they don't interfere.
• Replay / inspect — every run lands in a session folder with raw outputs, parsed JSON, and a JSONL execution log.
• Studio integration — pin a session, watch live state, stop a run from the UI.

You're not replacing the agent. You're giving it a job description, a contract, and a place in a pipeline.

---

Companion packages

Package	What it adds
@zibby/skills	Pre-built skills (browser via Playwright MCP, GitHub, Jira, Slack, memory).

Workflow itself ships zero agent strategies and zero skills — bring your own, or npm install @zibby/skills for pre-built skills.

---

Status

0.1.x. The public protocol surface is stable and consumed by Zibby Studio + tooling:

• 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 }

The JS API is still pre-1.0 — minor versions may add or rename surface area, breaking changes will be called out in release notes.

---

License

MIT