Add Documentation for AGS (#4711)

* enable download of team specs

* add docs v1 for ags to documentation website

* update docs readme/image

* Update python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/usage.md

Co-authored-by: Eric Zhu <[email protected]>

* Update python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/index.md

Co-authored-by: Eric Zhu <[email protected]>

---------

Co-authored-by: Eric Zhu <[email protected]>

Author: victordibia

python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/faq.md

@@ -0,0 +1,78 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      FAQ for AutoGen Studio - A low code tool for building and debugging multi-agent systems
+---
+
+# FAQ
+
+## Q: How do I specify the directory where files(e.g. database) are stored?
+
+A: You can specify the directory where files are stored by setting the `--appdir` argument when running the application. For example, `autogenstudio ui --appdir /path/to/folder`. This will store the database (default) and other files in the specified directory e.g. `/path/to/folder/database.sqlite`.
+
+## Q: Can I use other models with AutoGen Studio?
+
+Yes. AutoGen standardizes on the openai model api format, and you can use any api server that offers an openai compliant endpoint. In the AutoGen Studio UI, each agent has an `model_client` field where you can input your model endpoint details including `model`, `api key`, `base url`, `model type` and `api version`. For Azure OpenAI models, you can find these details in the Azure portal. Note that for Azure OpenAI, the `model name` is the deployment id or engine, and the `model type` is "azure".
+For other OSS models, we recommend using a server such as vllm, LMStudio, Ollama, to instantiate an openai compliant endpoint.
+
+## Q: The server starts but I can't access the UI
+
+A: If you are running the server on a remote machine (or a local machine that fails to resolve localhost correctly), you may need to specify the host address. By default, the host address is set to `localhost`. You can specify the host address using the `--host <host>` argument. For example, to start the server on port 8081 and local address such that it is accessible from other machines on the network, you can run the following command:
+
+```bash
+autogenstudio ui --port 8081 --host 0.0.0.0
+```
+
+## Q: Can I export my agent workflows for use in a python app?
+
+Yes. In the Team Builder view, you select a team and download its specification. This file can be imported in a python application using the `TeamManager` class. For example:
+
+```python
+
+from autogenstudio.teammanager import TeamManager
+
+tm = TeamManager()
+result_stream =  tm.run(task="What is the weather in New York?", team_config="team.json") # or wm.run_stream(..)
+
+```
+
+<!-- ## Q: Can I deploy my agent workflows as APIs?
+
+Yes. You can launch the workflow as an API endpoint from the command line using the `autogenstudio` commandline tool. For example:
+
+```bash
+autogenstudio serve --workflow=workflow.json --port=5000
+```
+
+Similarly, the workflow launch command above can be wrapped into a Dockerfile that can be deployed on cloud services like Azure Container Apps or Azure Web Apps. -->
+
+## Q: Can I run AutoGen Studio in a Docker container?
+
+A: Yes, you can run AutoGen Studio in a Docker container. You can build the Docker image using the provided [Dockerfile](https://github.com/microsoft/autogen/blob/autogenstudio/samples/apps/autogen-studio/Dockerfile) and run the container using the following commands:
+
+```bash
+FROM python:3.10
+
+WORKDIR /code
+
+RUN pip install -U gunicorn autogenstudio
+
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    AUTOGENSTUDIO_APPDIR=/home/user/app
+
+WORKDIR $HOME/app
+
+COPY --chown=user . $HOME/app
+
+CMD gunicorn -w $((2 * $(getconf _NPROCESSORS_ONLN) + 1)) --timeout 12600 -k uvicorn.workers.UvicornWorker autogenstudio.web.app:app --bind "0.0.0.0:8081"
+```
+
+Using Gunicorn as the application server for improved performance is recommended. To run AutoGen Studio with Gunicorn, you can use the following command:
+
+```bash
+gunicorn -w $((2 * $(getconf _NPROCESSORS_ONLN) + 1)) --timeout 12600 -k uvicorn.workers.UvicornWorker autogenstudio.web.app:app --bind
+```

python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/index.md

@@ -0,0 +1,111 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      User Guide for AutoGen Studio - A low code tool for building and debugging multi-agent systems
+---
+
+# AutoGen Studio
+
+[![PyPI version](https://badge.fury.io/py/autogenstudio.svg)](https://badge.fury.io/py/autogenstudio)
+[![Downloads](https://static.pepy.tech/badge/autogenstudio/week)](https://pepy.tech/project/autogenstudio)
+
+AutoGen Studio is a low-code interface built to help you rapidly prototype AI agents, enhance them with tools, compose them into teams and interact with them to accomplish tasks. It is built on [AutoGen AgentChat](https://microsoft.github.io/autogen) - a high-level API for building multi-agent applications.
+
+![AutoGen Studio](https://media.githubusercontent.com/media/microsoft/autogen/refs/heads/main/python/packages/autogen-studio/docs/ags_screen.png)
+
+Code for AutoGen Studio is on GitHub at [microsoft/autogen](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-studio)
+
+```{caution}
+AutoGen Studio is meant to help you rapidly prototype multi-agent workflows and demonstrate an example of end user interfaces built with AutoGen. It is not meant to be a production-ready app. Developers are encouraged to use the AutoGen framework to build their own applications, implementing authentication, security and other features required for deployed applications.
+```
+
+## Capabilities - What Can You Do with AutoGen Studio?
+
+AutoGen Studio offers four main interfaces to help you build and manage multi-agent systems:
+
+1. **Team Builder**
+
+   - A visual interface for creating agent teams through declarative specification (JSON) or drag-and-drop
+   - Supports configuration of all core components: teams, agents, tools, models, and termination conditions
+   - Fully compatible with AgentChat's component definitions
+
+2. **Playground**
+
+   - Interactive environment for testing and running agent teams
+   - Features include:
+     - Live message streaming between agents
+     - Visual representation of message flow through a control transition graph
+     - Interactive sessions with teams using UserProxyAgent
+     - Full run control with the ability to pause or stop execution
+
+3. **Gallery**
+
+   - Central hub for discovering and importing community-created components
+   - Enables easy integration of third-party components
+
+4. **Deployment**
+   - Export and run teams in python code
+   - Setup and test endpoints based on a team configuration
+   - Run teams in a docker container
+
+This revision improves clarity by:
+
+- Organizing capabilities into clearly numbered sections
+- Using more precise language
+- Breaking down complex features into digestible points
+- Maintaining consistent formatting and structure
+- Eliminating awkward phrasing and grammatical issues
+- Adding context about how each interface serves users
+
+### Roadmap
+
+Review project roadmap and issues [here](https://github.com/microsoft/autogen/issues/4006) .
+
+## Contribution Guide
+
+We welcome contributions to AutoGen Studio. We recommend the following general steps to contribute to the project:
+
+- Review the overall AutoGen project [contribution guide](https://github.com/microsoft/autogen/blob/main/CONTRIBUTING.md)
+- Please review the AutoGen Studio [roadmap](https://github.com/microsoft/autogen/issues/4006) to get a sense of the current priorities for the project. Help is appreciated especially with Studio issues tagged with `help-wanted`
+- Please use the tag [`proj-studio`](https://github.com/microsoft/autogen/issues?q=is%3Aissue%20state%3Aopen%20label%3Aproj-studio) tag for any issues, questions, and PRs related to Studio
+- Please initiate a discussion on the roadmap issue or a new issue to discuss your proposed contribution.
+- Submit a pull request with your contribution!
+- If you are modifying AutoGen Studio, it has its own devcontainer. See instructions in `.devcontainer/README.md` to use it
+
+## A Note on Security
+
+AutoGen Studio is a research prototype and is **not meant to be used** in a production environment. Some baseline practices are encouraged e.g., using Docker code execution environment for your agents.
+
+However, other considerations such as rigorous tests related to jailbreaking, ensuring LLMs only have access to the right keys of data given the end user's permissions, and other security features are not implemented in AutoGen Studio.
+
+If you are building a production application, please use the AutoGen framework and implement the necessary security features.
+
+## Acknowledgements and Citation
+
+AutoGen Studio is based on the [AutoGen](https://microsoft.github.io/autogen) project. It was adapted from a research prototype built in October 2023 (original credits: Victor Dibia, Gagan Bansal, Adam Fourney, Piali Choudhury, Saleema Amershi, Ahmed Awadallah, Chi Wang).
+
+If you use AutoGen Studio in your research, please cite the following paper:
+
+```
+@inproceedings{autogenstudio,
+  title={AUTOGEN STUDIO: A No-Code Developer Tool for Building and Debugging Multi-Agent Systems},
+  author={Dibia, Victor and Chen, Jingya and Bansal, Gagan and Syed, Suff and Fourney, Adam and Zhu, Erkang and Wang, Chi and Amershi, Saleema},
+  booktitle={Proceedings of the 2024 Conference on Empirical Methods in Natural Language Processing: System Demonstrations},
+  pages={72--79},
+  year={2024}
+}
+```
+
+## Next Steps
+
+To begin, follow the [installation instructions](installation.md) to install AutoGen Studio.
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+installation
+usage
+faq
+```

python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/installation.md

@@ -0,0 +1,69 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      User Guide for AutoGen Studio - A low code tool for building and debugging multi-agent systems
+---
+
+# Installation
+
+There are two ways to install AutoGen Studio - from PyPi or from source. We **recommend installing from PyPi** unless you plan to modify the source code.
+
+1.  **Install from PyPi**
+
+    We recommend using a virtual environment (e.g., conda) to avoid conflicts with existing Python packages. With Python 3.10 or newer active in your virtual environment, use pip to install AutoGen Studio:
+
+    ```bash
+    pip install -U autogenstudio
+    ```
+
+2.  **Install from Source**
+
+    > Note: This approach requires some familiarity with building interfaces in React.
+
+    If you prefer to install from source, ensure you have Python 3.10+ and Node.js (version above 14.15.0) installed. Here's how you get started:
+
+    - Clone the AutoGen Studio repository and install its Python dependencies:
+
+      ```bash
+      pip install -e .
+      ```
+
+    - Navigate to the `samples/apps/autogen-studio/frontend` directory, install dependencies, and build the UI:
+
+      ```bash
+      npm install -g gatsby-cli
+      npm install --global yarn
+      cd frontend
+      yarn install
+      yarn build
+      ```
+
+For Windows users, to build the frontend, you may need alternative commands to build the frontend.
+
+```bash
+
+  gatsby clean && rmdir /s /q ..\\autogenstudio\\web\\ui 2>nul & (set \"PREFIX_PATH_VALUE=\" || ver>nul) && gatsby build --prefix-paths && xcopy /E /I /Y public ..\\autogenstudio\\web\\ui
+
+```
+
+### Running the Application
+
+Once installed, run the web UI by entering the following in a terminal:
+
+```bash
+autogenstudio ui --port 8081 --appdir /path/to/folder
+```
+
+This will start the application on the specified port. Open your web browser and go to `http://localhost:8081/` to begin using AutoGen Studio.
+
+AutoGen Studio also takes several parameters to customize the application:
+
+- `--host <host>` argument to specify the host address. By default, it is set to `localhost`.
+- `--appdir <appdir>` argument to specify the directory where the app files (e.g., database and generated user files) are stored. By default, it is set to the a `.autogenstudio` directory in the user's home directory.
+- `--port <port>` argument to specify the port number. By default, it is set to `8080`.
+- `--upgrade-database` argument to upgrade the database schema (assuming there are changes in the version you are installing). By default, it is set to `False`.
+- `--reload` argument to enable auto-reloading of the server when changes are made to the code. By default, it is set to `False`.
+- `--database-uri` argument to specify the database URI. Example values include `sqlite:///database.sqlite` for SQLite and `postgresql+psycopg://user:password@localhost/dbname` for PostgreSQL. If this is not specified, the database URI defaults to a `database.sqlite` file in the `--appdir` directory.
+
+Now that you have AutoGen Studio installed and running, you are ready to explore its capabilities, including defining and modifying agent workflows, interacting with agents and sessions, and expanding agent skills.

python/packages/autogen-core/docs/src/user-guide/autogenstudio-user-guide/usage.md

@@ -0,0 +1,55 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      Usage for AutoGen Studio - A low code tool for building and debugging multi-agent systems
+---
+
+# Usage
+
+The expected usage behavior is that developers use the provided Team Builder interface to to define teams - create agents, attach tools and models to agents, and define termination conditions. Once the team is defined, users can run the team in the Playground to interact with the team to accomplish tasks.
+
+![AutoGen Studio](https://media.githubusercontent.com/media/microsoft/autogen/refs/heads/main/python/packages/autogen-studio/docs/ags_screen.png)
+
+## Building an Agent Team
+
+AutoGen Studio is tied very closely with all of the component abstractions provided by AutoGen AgentChat. This includes - {py:class}`~autogen_agentchat.teams`, {py:class}`~autogen_agentchat.agents`, {py:class}`~autogen_core.models`, {py:class}`~autogen_core.tools`, {py:class}`~autogen_agentchat.conditions`.
+
+Users can define these components in the Team Builder interface either via a declarative specification or by dragging and dropping components from a component library.
+
+## Testing an Agent Team
+
+AutoGen Studio Playground allows users to interactively test teams on tasks and review resulting artifacts (such as images, code, and documents).
+
+Users can also review the “inner monologue” of team as they address tasks, and view profiling information such as costs associated with the run (such as number of turns, number of tokens etc.), and agent actions (such as whether tools were called and the outcomes of code execution).
+
+## Importing and Reusing Team Configurations
+
+AutoGen Studio provides a Gallery view where users can import components from 3rd party community sources. This allows users to reuse and share team configurations with others.
+
+- Gallery -> New Gallery -> Import
+- Set as default gallery
+- Reuse components in Team Builder
+
+### Using AutoGen Studio Teams in a Python Application
+
+An exported team can be easily integrated into any Python application using the `TeamManager` class with just two lines of code. Underneath, the `TeamManager` rehydrates the workflow specification into AutoGen agents that are subsequently used to address tasks.
+
+```python
+
+from autogenstudio.teammanager import TeamManager
+
+tm = TeamManager()
+result_stream =  tm.run(task="What is the weather in New York?", team_config="team.json") # or wm.run_stream(..)
+
+```
+
+<!-- ### Deploying AutoGen Studio Teams as APIs
+
+The team can be launched as an API endpoint from the command line using the autogenstudio commandline tool.
+
+```bash
+autogenstudio serve --workflow=workflow.json --port=5000
+```
+
+Similarly, the workflow launch command above can be wrapped into a Dockerfile that can be deployed on cloud services like Azure Container Apps or Azure Web Apps. -->

python/packages/autogen-core/docs/src/user-guide/index.md

@@ -5,6 +5,7 @@
 :hidden:
 
 agentchat-user-guide/index
+autogenstudio-user-guide/index
 core-user-guide/index
 extensions-user-guide/index
 ```
@@ -19,6 +20,18 @@ extensions-user-guide/index
 :class-item: api-card
 :::
 
+:::{grid-item-card} {fas}`people-group;pst-color-primary` <br> AutoGen AgentChat
+:link: autogenstudio-user-guide/index
+:link-type: doc
+:class-item: api-card
+:::
+
+:::{grid-item-card} {fas}`display;pst-color-primary` <br> AutoGen Studio
+:link: autogenstudio-user-guide/index
+:link-type: doc
+:class-item: api-card
+:::
+
 :::{grid-item-card} {fas}`cube;pst-color-primary` <br> AutoGen Core
 :link: core-user-guide/index
 :link-type: doc
@@ -27,9 +40,8 @@ extensions-user-guide/index
 
 ::::
 
-
 <script type="text/javascript">
     setTimeout(function() {
         window.location.href = "agentchat-user-guide/quickstart.html";
     }, 0);
-</script>
+</script>

python/packages/autogen-studio/docs/ags_screen.png

@@ -18,7 +18,7 @@ import {
 } from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
 import { Button, Layout, message, Modal, Switch, Tooltip } from "antd";
-import { Cable, Code2, Save } from "lucide-react";
+import { Cable, Code2, Download, Save } from "lucide-react";
 import { useTeamBuilderStore } from "./store";
 import { ComponentLibrary } from "./library";
 import { ComponentTypes, Team } from "../../../types/datamodel";
@@ -292,6 +292,24 @@ export const TeamBuilder: React.FC<TeamBuilderProps> = ({
           </span>
         </div>
         <div>
+          <Tooltip title="Download Team Configuration">
+            <Button
+              type="text"
+              icon={<Download size={18} />}
+              className="p-1.5 hover:bg-primary/10 rounded-md text-primary/75 hover:text-primary"
+              onClick={() => {
+                const json = JSON.stringify(syncToJson(), null, 2);
+                const blob = new Blob([json], { type: "application/json" });
+                const url = URL.createObjectURL(blob);
+                const a = document.createElement("a");
+                a.href = url;
+                a.download = "team-config.json";
+                a.click();
+                URL.revokeObjectURL(url);
+              }}
+            />
+          </Tooltip>
+
           <Tooltip title="Save Changes">
             <Button
               type="text"