waldiez 0.5.1

Make AG2 Agents Collaborate: Drag, Drop, and Orchestrate with Waldiez.

Waldiez

Make AG2 Agents Collaborate: Drag, Drop, and Orchestrate with Waldiez

Design AI Agents and translate a Waldiez flow to AG2:

Features

• Convert .waldiez flows to .py or .ipynb
• Run a .waldiez flow
• Store the runtime logs of a flow to csv for further analysis

Installation

Python

On PyPI:

python -m pip install waldiez

From the repository:

python -m pip install git+https://github.com/waldiez/waldiez.git

React Component

If you’re looking for the React component, please refer to README.npm.

Note: The React component is only for creating and editing flows — it is not needed to convert or run flows (that functionality is handled by the Python package).

To add the waldiez library to your app:

npm install @waldiez/react
# or
yarn add @waldiez/react
# or
pnpm add @waldiez/react
# or
bun add @waldiez/react

Usage

UI Options

• For creating-only (no exporting or running) waldiez flows, you can use the playground at https://waldiez.github.io.
• There is also a jupyterlab extension here: waldiez/jupyter
• You also can use the vscode extension:
  • repo
  • marketplace
• Finally, you can use waldiez-studio, which includes a FastAPI app to handle the conversion and running of waldiez flows.

The jupyterlab extension and waldiez studio are also provided as extras in the main package.

pip install waldiez[studio]  # or pip install waldiez_studio
pip install waldiez[jupyter]  # or pip install waldiez_jupyter
# or both
pip install waldiez[studio,jupyter]

CLI

# Convert a Waldiez flow to a python script or a jupyter notebook
waldiez convert --file /path/to/a/flow.waldiez --output /path/to/an/output/flow[.py|.ipynb]
# Convert and run the script, optionally force generation if the output file already exists
waldiez run --file /path/to/a/flow.waldiez --output /path/to/an/output/flow[.py|.ipynb] [--force]

Using docker/podman

🪟 Windows (PowerShell with Docker or Podman Desktop)

$hostInputFile = "C:\Users\YourName\Documents\flow.waldiez"
$containerInputFile = "/home/waldiez/workspace/flow.waldiez"
$hostOutputDir = "C:\Users\YourName\Documents\waldiez_output"
$containerOutputDir = "/home/waldiez/output"
$containerOutputFile = "/home/waldiez/output/flow.ipynb"

# Convert a flow to Jupyter Notebook
docker run --rm `
  -v "$hostInputFile:$containerInputFile" `
  -v "$hostOutputDir:$containerOutputDir" `
  waldiez/waldiez convert --file $hostInputFile --output $containerOutputFile

# Convert and run it
docker run --rm `
  -v "$flow:/home/waldiez/workspace/flow.waldiez" `
  -v "$output:/output" `
  waldiez/waldiez run --file $hostInputFile --output $containerOutputFile

Note If using Hyper-V mode, make sure your files are in a shared folder Docker Desktop has access to.
More info: https://docs.docker.com/desktop/settings/windows/#file-sharing

🐧 Linux/macOS/WSL (Docker or Podman)

CONTAINER_COMMAND=docker # or podman
# Asuming ./flow.waldiez exists
HOST_INPUT="$(pwd)/flow.waldiez"
CONTAINER_INPUT="/home/waldiez/workspace/flow.waldiez"
HOST_OUTPUT_DIR="$(pwd)/output"
CONTAINER_OUTPUT_DIR="/home/waldiez/output"
mkdir -p ${HOST_OUTPUT_DIR}

# Convert a flow to a Python script
$CONTAINER_COMMAND run --rm \
  -v ${HOST_INPUT}:${CONTAINER_INPUT} \
  -v ${HOST_OUTPUT_DIR}:${CONTAINER_OUTPUT_DIR} \
  waldiez/waldiez convert --file $HOST_INPUT --output ${CONTAINER_OUTPUT_DIR}/flow.py

# Convert to a Jupyter Notebook instead
$CONTAINER_COMMAND run --rm \
  -v ${HOST_INPUT}:${CONTAINER_INPUT} \
  -v ${HOST_OUTPUT_DIR}:${CONTAINER_OUTPUT_DIR} \
  waldiez/waldiez convert --file $HOST_INPUT --output ${CONTAINER_OUTPUT_DIR}/flow.ipynb

# Convert and run it (force override generated file if it exists)
$CONTAINER_COMMAND run --rm -it \
  -v ${HOST_INPUT}:${CONTAINER_INPUT} \
  -v ${HOST_OUTPUT_DIR}:${CONTAINER_OUTPUT_DIR} \
  waldiez/waldiez run --file $HOST_INPUT --force

As a library

Export a flow

# Export a Waldiez flow to a python script or a jupyter notebook
from waldiez import WaldiezExporter
flow_path = "/path/to/a/flow.waldiez"
output_path = "/path/to/an/output.py"  # or .ipynb
exporter = WaldiezExporter.load(flow_path)
exporter.export(output_path)

Run a flow

# Run a flow
from waldiez import WaldiezRunner
flow_path = "/path/to/a/flow.waldiez"
output_path = "/path/to/an/output.py"
runner = WaldiezRunner.load(flow_path)
runner.run(output_path=output_path)

Tools

• ag2 (formerly AutoGen)
• juptytext
• pydantic
• typer
• asyncer

Known Conflicts

• autogen-agentchat: This package conflicts with ag2. Ensure that autogen-agentchat is uninstalled before installing waldiez. If you have already installed autogen-agentchat, you can uninstall it with the following command:

  pip uninstall autogen-agentchat -y
  

  If already installed waldiez you might need to reinstall it after uninstalling autogen-agentchat:

  pip install --force --no-cache waldiez ag2
  

See also

• Waldiez Playground
• React Component
• Waldiez Studio
• Waldiez JupyterLab Extension
• Waldiez VSCode Extension

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Panagiotis Kasnesis 📆 🔬	Lazaros Toumanidis 💻	Stella Ioannidou 📣 🎨	Amalia Contiero 💻 🐛	Christos Chatzigeorgiou 💻
Add your contributions

License

This project is licensed under the Apache License, Version 2.0 (Apache-2.0).