Python API

The verdog-runtime package provides the declarations, execution engine, and agent interfaces used by workflow projects. It requires Python 3.12 or later and is distributed through PyPI. The verdog management command is provided separately by verdog-cli.

Installation

For direct runtime use in a Python application, create a virtual environment in the application's directory:

python -m venv .venv

Install the package using that environment's interpreter:

Linux / macOS

.venv/bin/python -m pip install verdog-runtime

Windows

.\.venv\Scripts\python.exe -m pip install verdog-runtime

Run the application's Python code with the same interpreter. Python modules use the name verdog_runtime.

Generated workflow projects already declare their runtime requirement in pyproject.toml. Retain that version and use the project's editor and workflow environments.

Workflow declarations

verdog_runtime.declarations defines graph components, visit contexts, and result types. Generated modules use these declarations to connect a project's authored types and functions to its graph.

Reference	Purpose
Workflow and Subroutine	Entry points, boundary types, parameters, and execution environments.
Node and Edge	Operations and control flow.
Visit	Typed implementations, contexts, and return values.
Feature and State	Feature values and node-local state.
Profile and Session	Agent provider configuration and conversation lifetime.

Edit behavior in the authored impl.py files. Generated declarations are updated through graph operations; see Ownership.

Execution

verdog_runtime.interpreter.Dispatcher executes a workflow definition synchronously. It accepts the definition and typed input, together with an output directory and optional execution settings.

from pathlib import Path

from verdog_runtime.interpreter import CheckpointPolicy, Dispatcher

dispatcher = Dispatcher(project_root=Path.cwd())
result = dispatcher.run(
    definition,
    input_value,
    output_dir=Path("artifacts/run"),
    checkpointing=CheckpointPolicy.AUTO,
)

Here, definition is the workflow definition exported by the generated project, and input_value is an instance of its declared input type. The selected Python environment must contain the runtime, the workflow package, and the workflow's dependencies.

The dispatcher also provides resume(), restart(), and fork(). Their parameters, checkpoint policies, session policies, and cancellation behavior are described in Runs and resumption.

Results and exceptions

Visits return the result type specified by their generated signature. Ordinary visits return Success; feature visits return FeatureSuccess. Exceptions propagate according to the workflow's call and failure boundaries. See Visit for signatures and Exceptions for error handling.

Agent integration

Agent visits use the profile and session selected by their node. Applications may provide a custom invoker implementing the runtime's AgentInvoker interface. Persistent conversations and checkpoint branching require the corresponding session capabilities. See Profile, Session, and conversation branching.