Skip to content
Petal Labs Petal Labs Docs

Petal Flow Overview

Petal Flow

Section titled “Petal Flow”

Petal Flow is an open-source Go workflow runtime for building AI agent systems as explicit, testable graphs. You can run workflows from Go code, the CLI, or an HTTP daemon.

Why Petal Flow

Section titled “Why Petal Flow”

Graph-first execution

Build workflows as nodes and edges with clear control flow and replayable runs.

AI + tools

Combine LLM nodes, tool calls, routing, transforms, human gates, and validation.

Daemon + persistence

Persist workflows, tool registrations, schedules, and run events in SQLite.

Production observability

Stream runtime events and export traces/metrics with OpenTelemetry.

Workflow Formats

Section titled “Workflow Formats”

Petal Flow supports two authoring formats:

  • Agent/Task workflows (.yaml, .yml, .json) for high-level authoring
  • Graph IR workflows (.json) for runtime-oriented node/edge definitions

Agent/Task workflows compile to Graph IR before execution.

version: "1.0"
schema_version: "1.0.0"
kind: agent_workflow
id: research_workflow
name: Research Assistant

Recent Platform Updates

Section titled “Recent Platform Updates”
  • Semver schema contract for workflow schema_version with normalized kind
  • Webhook nodes (webhook_trigger, webhook_call) for inbound and outbound webhook automation
  • UTC cron schedules in daemon mode for recurring workflow runs
  • SQLite-only persistence for workflows, tools, schedules, and event records
  • Improved run/tool validation for stored tool actions and daemon execution paths

How It Fits with Iris

Section titled “How It Fits with Iris”

Use Iris providers inside Petal Flow nodes for LLM calls while Petal Flow handles orchestration.

providers, _ := hydrate.ResolveProviders(nil)
factory := hydrate.NewLiveNodeFactory(providers, llmprovider.NewClient)
graph, _ := hydrate.HydrateGraph(definition, providers, factory)
Section titled “Quick Links”
Getting Started Run your first workflow from CLI and Go.
CLI Reference Commands, flags, daemon endpoints, and tools.
Concepts Graphs, nodes, envelopes, runtime events, and step control.
API Reference Core package and runtime API map.
Examples Official runnable examples from the PetalFlow repository.