Flows

A flow is a directed acyclic graph of nodes: HTTP calls, file readers, database queries, Python scripts and agents. Each node receives the results of its parents, and a node starts as soon as all its parents are done, so independent branches run in parallel. A flow is plain data: it is written in YAML or JSON, versioned with your code, run from Python or the command line, and made durable with Temporal.

A first flow

flows/news_summary.yaml

name: News Summary Pipeline

nodes:
  - name: fetch_news
    type: gwenflow.httpRequest
    parameters:
      url: https://hacker-news.firebaseio.com/v0/topstories.json
      method: GET

  - name: summarize
    type: gwenflow.Agent
    parameters:
      model: openai/gpt-5-mini
      instructions: You are a tech journalist who writes concise summaries.
      task: "Here are today's top Hacker News story IDs:\n\n{fetch_news}\n\nWhat topics are trending?"

connections:
  fetch_news:
    - - node: summarize
        type: main
        index: 0

from gwenflow import FlowRunner

results = FlowRunner("flows/news_summary.yaml").run()   # every node's result, keyed by node name
print(results["summarize"])

Or from a terminal: gwenflow run flows/news_summary.yaml.

The definition

Nodes

Key	Meaning
`name`	unique in the flow: how connections, placeholders and results refer to the node
`type`	the node type, e.g. `gwenflow.Agent`. See Node types.
`parameters`	the node type’s parameters
`credentials`	parameter name → environment variable holding its value
`settings`	`timeout` (seconds) and `retries` (extra attempts); no timeout and no retry by default
`id`, `version`, `position`	optional: an id (generated when missing), a version, a position for graphical editors

Connections

connections maps a source node to the nodes that receive its output. The value is a list of output ports, each a list of targets:

connections:
  fetch_prices:
    - - node: analyse
      - node: archive
  fetch_news:
    - - node: analyse

Here analyse waits for both fetch_prices and fetch_news, which run in parallel; archive starts as soon as fetch_prices is done. The flow itself takes name and settings. Flow-level settings (node_timeout, node_retries) are defaults for the nodes of a durable run; a local run only reads each node’s own settings.

What a node receives

A node gets its parents’ results as a dict keyed by parent name. An agent node fills the {node_name} placeholders of its task with them and appends the parents it does not reference as context. Writer nodes take the output of their parent (or of the one named in source).

Validation

A flow is validated when it is loaded: duplicate node names, connections to unknown nodes and cycles raise FlowError, before anything runs.

Running

from gwenflow.flows import Flow, FlowError, FlowRunner

flow = Flow.from_file("flows/news_summary.yaml")   # YAML or JSON, by extension

results = flow.run()                                # sync
results = await flow.arun()                         # async

def on_status(node: str, status: str) -> None:      # running, done, failed
    print(f"{node}: {status}")

results = await flow.arun(on_status=on_status)

FlowRunner(path_or_flow) wraps a flow with a tracing span and graph plotting: run(), arun(), plot() (a PNG, needs pydot) and plot_interactive() (an HTML page, needs pyvis). flow.sinks() names the output nodes, those no other node consumes; flow.topological_order() the order the nodes resolve in.

Failures

Locally, each node runs in a worker thread. A node that raises is retried settings.retries times with a backoff; a node that exceeds settings.timeout fails. When a node is out of retries, the nodes still running are cancelled and FlowNodeError (a FlowError) is raised, naming the node:

try:
    results = FlowRunner("flows/news_summary.yaml").run()
except FlowError as e:
    print(e)    # Node 'fetch_news' failed: ...

Credentials

Keep secrets out of flow files: credentials maps a parameter to an environment variable, read only when the node runs.

  - name: orders
    type: gwenflow.postgresQuery
    parameters:
      host: db.internal
      database: shop
      user: reporting
      query: SELECT * FROM orders WHERE created_at > now() - interval '1 day'
    credentials:
      password: SHOP_DB_PASSWORD
    settings:
      timeout: 60
      retries: 2

A missing variable fails the node with a message naming it. In a durable run, the value never enters the workflow history.

Flows in Python

Flow.from_dict() builds a flow from the same structure as the YAML file, and flow.to_dict() returns it, so a flow can be generated, stored or sent over the wire:

flow = Flow.from_dict({
    "name": "Wiki brief",
    "nodes": [
        {"name": "research", "type": "gwenflow.Agent",
         "parameters": {"model": "openai/gpt-5-mini", "task": "Research Ada Lovelace.", "tools": ["wikipedia"]}},
        {"name": "brief", "type": "gwenflow.Agent",
         "parameters": {"model": "anthropic/claude-sonnet-4-6", "task": "Write a 5-line brief from: {research}"}},
    ],
    "connections": {"research": [[{"node": "brief"}]]},
})
print(flow.run()["brief"])

For two agents in a row, plain code is often enough:

joke = joker.run("Tell me a joke about programmers.").content
explanation = explainer.run(f"Explain why this joke is funny:\n\n{joke}").content

Flows pay off when the graph has parallel branches, data steps, retries, or must be stored, scheduled or run durably.

Flows vs. teams

In a flow, you fix the graph; in a team or with sub-agents, the orchestrator’s model decides at run time whom to ask. AutoFlow sits in between: a model plans the graph once, and the flow then runs as written.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Knowledge

Production

Project

Flows

A first flow

The definition

Nodes

Connections

What a node receives

Validation

Running

Failures

Credentials

Flows in Python

Flows vs. teams

​A first flow

​The definition

​Nodes

​Connections

​What a node receives

​Validation

​Running

​Failures

​Credentials

​Flows in Python

​Flows vs. teams

A first flow

The definition

Nodes

Connections

What a node receives

Validation

Running

Failures

Credentials

Flows in Python

Flows vs. teams