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 used for converting or running 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:
- 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
# Assuming ./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
Generate a script or a notebook from a flow
# Export a Waldiez flow to a python script or a jupyter notebook
from pathlib import Path
from waldiez import WaldiezExporter
flow_path = "/path/to/a/flow.waldiez"
output_path = "/path/to/an/output.py" # or .ipynb
exporter = WaldiezExporter.load(Path(flow_path))
exporter.export(output_path)
Run a flow
# Run a flow
from pathlib import Path
from waldiez import WaldiezRunner
flow_path = "/path/to/a/flow.waldiez"
output_path = "/path/to/an/output.py"
runner = WaldiezRunner.load(Path(flow_path))
runner.run(output_path=output_path)
Known Conflicts
-
autogen-agentchat: This package conflicts with
ag2. Ensure thatautogen-agentchatis uninstalled before installingwaldiez. If you have already installedautogen-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 💻 |
||
 Kunal Mhaske 🐛 |
||||||
Add your contributions
|
||||||
License
This project is licensed under the Apache License, Version 2.0 (Apache-2.0).
1 maintainer
Metadata
1 maintainer
Release files for waldiez 0.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| waldiez-0.7.1.tar.gz | 316.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| waldiez-0.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 786.3 kB
Release files / waldiez-0.7.1.tar.gz
| Download URL | waldiez-0.7.1.tar.gz |
|---|---|
| Size | 316.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2fd0d72e4bfeaca5d43f8b6a80fa1caa2ccd43fa438ea57853843b1a288de468
|
|
BLAKE2b-256 checksum How to use checksums |
20e2a1402407a7aac1e94582209dab1d509bc550fdd0ba009fb4d3c182a42536
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 13, 2026.
Transparency logRelease files / waldiez-0.7.1-py3-none-any.whl
| Download URL | waldiez-0.7.1-py3-none-any.whl |
|---|---|
| Size | 470.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e12f8bb6512b57f01a6e960d5efd50902e005dc587028f0dbdc2eca52382cfa8
|
|
BLAKE2b-256 checksum How to use checksums |
70b0b35f6745f5bc76e0c27525f22fa04f9349a9bc89743d72347e8def29ebca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 13, 2026.
Transparency log
