Merge pull request #4 from willeppy/main

Add full agdebugger code

Author: gagb

.github/screenshots/agdebugger_sc.png

@@ -0,0 +1,163 @@
+## GENERIC IGNORES
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+.pdm.toml
+
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.ruff_cache/
+
+/docs/src/reference
+.DS_Store
+
+# Generated proto files
+src/agnext/worker/protos/agent*
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.vite
+
+## SPECIFIC IGNORES
+
+demo

.gitignore

@@ -0,0 +1,28 @@
+# Development
+
+## Backend
+
+```sh
+# Install editable
+pip install -e .
+
+AGDEBUGGER_BACKEND_SERVE_UI=FALSE agdebugger scenario:get_agent_team --port 8123
+```
+
+## Frontend
+
+First time
+
+```sh
+cd frontend
+# Create a .env.development.local file with the required API URL
+echo "VITE_AGDEBUGGER_FRONTEND_API_URL=http://localhost:8123/api" > .env.development.local
+npm install
+```
+
+Later can just launch dev server
+
+```sh
+cd frontend
+npm run dev
+```

DEV.md

@@ -0,0 +1 @@
+graft frontend/dist

MANIFEST.in

@@ -1,33 +1,71 @@
-# Project
+# AGDebugger
 
-> This repo has been populated by an initial template to help get you started. Please
-> make sure to update the content to build a great experience for community-building.
+AGDebugger is an interactive system to help you debug your agent teams. It offers interactions to:
 
-As the maintainer of this project, please make a few updates:
+1. Send and step through agent messages
+2. Edit previously sent agent messages and revert to earlier points in a conversation
+3. Navigate agent conversations with an interactive visualization
 
-- Improving this README.MD file to provide a great experience
-- Updating SUPPORT.MD with content about this project's support experience
-- Understanding the security reporting process in SECURITY.MD
-- Remove this section from the README
+![screenshot of AGDebugger interface](.github/screenshots/agdebugger_sc.png)
 
-## Contributing
+## Local Install
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+You can install AGDebugger locally by cloning the repo and installing the python package.
 
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+```sh
+# Install & build frontend
+cd frontend
+npm install
+npm run build
+# Install & build agdebugger python package
+cd ..
+pip install .
+```
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+## Usage
 
-## Trademarks
+AGDebugger is built on top of [AutoGen](https://microsoft.github.io/autogen/stable/). To use AGDebugger, you provide a python file that exposes a function that creates an [AutoGen AgentChat](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/index.html) team for debugging. You can then launch AgDebugger with this agent team.
 
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
-trademarks or logos is subject to and must follow 
-[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
-Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
-Any use of third-party trademarks or logos are subject to those third-party's policies.
+For example, the script below creates a simple agent team with a single WebSurfer agent.
+
+```python
+# scenario.py
+from autogen_agentchat.teams import MagenticOneGroupChat
+from autogen_agentchat.ui import Console
+from autogen_ext.agents.web_surfer import MultimodalWebSurfer
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+async def get_agent_team():
+    model_client = OpenAIChatCompletionClient(model="gpt-4o")
+
+    surfer = MultimodalWebSurfer(
+        "WebSurfer",
+        model_client=model_client,
+    )
+    team = MagenticOneGroupChat([surfer], model_client=model_client)
+
+    return team
+```
+
+We can then launch the interface with:
+
+```sh
+ agdebugger scenario:get_agent_team
+```
+
+Once in the interface, you can send a GroupChatStart message to the start the agent conversation and begin debugging!
+
+## Citation
+
+See our CHI 2025 paper for more details on the design and evaluation of AGDebugger.
+
+```bibtex
+@inproceedings{epperson25agdebugger,
+    title={Interactive Debugging and Steering of Multi-Agent AI Systems},
+    author={Will Epperson and Gagan Bansal and Victor Dibia and Adam Fourney and Jack Gerrits and Erkang Zhu and Saleema Amershi},
+    year={2025},
+    publisher = {Association for Computing Machinery},
+    booktitle = {Proceedings of the 2025 CHI Conference on Human Factors in Computing Systems},
+    series = {CHI '25}
+}
+```