Skip to content
Petal Labs Petal Labs Docs

Petal Flow Getting Started

Getting Started

Section titled “Getting Started”

This guide covers the fastest path to running Petal Flow from both the CLI and Go SDK.

Prerequisites

Section titled “Prerequisites”
  • Go 1.24+
  • A Go module (go mod init ...)

Install

Section titled “Install”
Terminal window
# SDK
go get github.com/petal-labs/petalflow


# CLI
go install github.com/petal-labs/petalflow/cmd/petalflow@latest

CLI Quickstart

Section titled “CLI Quickstart”
  1. Validate a workflow
  2. Compile Agent/Task to Graph IR
  3. Run with JSON input
Terminal window
# Validate (agent or graph workflow)
petalflow validate workflow.yaml


# Compile Agent/Task to Graph IR
petalflow compile workflow.yaml --output compiled.graph.json


# Execute
petalflow run compiled.graph.json --input '{"name":"World"}'

Minimal Agent/Task Workflow

Section titled “Minimal Agent/Task Workflow”
version: "1.0"
schema_version: "1.0.0"
kind: agent_workflow
id: hello_agent
name: Hello Agent


agents:
  greeter:
    role: Friendly assistant
    goal: Return a greeting
    provider: anthropic
    model: claude-sonnet-4-20250514


tasks:
  greet:
    description: Greet {{input.name}} in one sentence.
    agent: greeter
    expected_output: Greeting text


execution:
  strategy: sequential
  task_order: [greet]

Go SDK Quickstart

Section titled “Go SDK Quickstart”
package main


import (
  "context"
  "fmt"


  "github.com/petal-labs/petalflow"
)


func main() {
  g := petalflow.NewGraph("hello")


  greet := petalflow.NewFuncNode("greet", func(ctx context.Context, env *petalflow.Envelope) (*petalflow.Envelope, error) {
    name := env.GetVarString("name")
    env.SetVar("greeting", fmt.Sprintf("Hello, %s!", name))
    return env, nil
  })


  _ = g.AddNode(greet)
  _ = g.SetEntry("greet")


  env := petalflow.NewEnvelope().WithVar("name", "World")
  result, err := petalflow.NewRuntime().Run(context.Background(), g, env, petalflow.DefaultRunOptions())
  if err != nil {
    panic(err)
  }


  fmt.Println(result.GetVarString("greeting"))
}

Provider Credentials

Section titled “Provider Credentials”

You can pass provider keys per run:

Terminal window
petalflow run workflow.yaml --provider-key anthropic=sk-ant-...

Or use environment/config resolution (PETALFLOW_PROVIDER_<NAME>_API_KEY, config file, or both).

Next Steps

Section titled “Next Steps”