A programming framework for agentic AI
Transition to Pydata Sphinx Theme (#482)
Victor Dibiaeffde903c8e9
diff --git a/python/packages/autogen-core/.gitignore b/python/packages/autogen-core/.gitignoreindex 186e847cc..81bcd42b6 100644--- a/python/packages/autogen-core/.gitignore+++ b/python/packages/autogen-core/.gitignore@@ -161,7 +161,7 @@ cython_debug/.ruff_cache/-/docs/src/reference+/docs/src/reference/python.DS_Store# Generated log filesdiff --git a/python/packages/autogen-core/docs/README.md b/python/packages/autogen-core/docs/README.mdnew file mode 100644index 000000000..68ce29a9e--- /dev/null+++ b/python/packages/autogen-core/docs/README.md@@ -0,0 +1,37 @@+## Building the AGNext Documentation++AGNext documentation is based on the sphinx documentation system and uses the myst-parser to render markdown files. It uses the [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/) to style the documentation.++### Prerequisites++Ensure you have all of the dev dependencies for the `autogen-core` package installed. You can install them by running the following command from the root of the python repository:++```bash+uv sync+source .venv/bin/activate+```++## Building Docs++To build the documentation, run the following command from the root of the python repository:++```bash+poe --directory ./packages/autogen-core/ docs-build+```++To serve the documentation locally, run the following command from the root of the python repository:++```bash+poe --directory ./packages/autogen-core/ docs-serve+```++[!NOTE]+Sphinx will only rebuild files that have changed since the last build. If you want to force a full rebuild, you can delete the `./packages/autogen-core/docs/build` directory before running the `docs-build` command.++## Versioning the Documentation++The current theme - [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/) - supports [switching between versions](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html) of the documentation.++To version the documentation, you need to create a new version of the documentation by copying the existing documentation to a new directory with the version number. For example, to create a new version of the documentation for version `0.1.0`, you would run the following command:++How are various versions built? - TBD.diff --git a/python/packages/autogen-core/docs/src/_extension/gallery_directive.py b/python/packages/autogen-core/docs/src/_extension/gallery_directive.pynew file mode 100644index 000000000..80642c545--- /dev/null+++ b/python/packages/autogen-core/docs/src/_extension/gallery_directive.py@@ -0,0 +1,144 @@+"""A directive to generate a gallery of images from structured data.++Generating a gallery of images that are all the same size is a common+pattern in documentation, and this can be cumbersome if the gallery is+generated programmatically. This directive wraps this particular use-case+in a helper-directive to generate it with a single YAML configuration file.++It currently exists for maintainers of the pydata-sphinx-theme,+but might be abstracted into a standalone package if it proves useful.+"""++from pathlib import Path+from typing import Any, ClassVar, Dict, List++from docutils import nodes+from docutils.parsers.rst import directives+from sphinx.application import Sphinx+from sphinx.util import logging+from sphinx.util.docutils import SphinxDirective+from yaml import safe_load++logger = logging.getLogger(__name__)+++TEMPLATE_GRID = """+`````{{grid}} {columns}+{options}++{content}++`````+"""++GRID_CARD = """+````{{grid-item-card}} {title}+{options}++{content}+````+"""+++class GalleryGridDirective(SphinxDirective):+ """A directive to show a gallery of images and links in a Bootstrap grid.++ The grid can be generated from a YAML file that contains a list of items, or+ from the content of the directive (also formatted in YAML). Use the parameter+ "class-card" to add an additional CSS class to all cards. When specifying the grid+ items, you can use all parameters from "grid-item-card" directive to customize+ individual cards + ["image", "header", "content", "title"].++ Danger:+ This directive can only be used in the context of a Myst documentation page as+ the templates use Markdown flavored formatting.+ """++ name = "gallery-grid"+ has_content = True+ required_arguments = 0+ optional_arguments = 1+ final_argument_whitespace = True+ option_spec: ClassVar[dict[str, Any]] = {+ # A class to be added to the resulting container+ "grid-columns": directives.unchanged,+ "class-container": directives.unchanged,+ "class-card": directives.unchanged,+ }++ def run(self) -> List[nodes.Node]:+ """Create the gallery grid."""+ if self.arguments:+ # If an argument is given, assume it's a path to a YAML file+ # Parse it and load it into the directive content+ path_data_rel = Path(self.arguments[0])+ path_doc, _ = self.get_source_info()+ path_doc = Path(path_doc).parent+ path_data = (path_doc / path_data_rel).resolve()+ if not path_data.exists():+ logger.info(f"Could not find grid data at {path_data}.")+ nodes.text("No grid data found at {path_data}.")+ return+ yaml_string = path_data.read_text()+ else:+ yaml_string = "\n".join(self.content)++ # Use all the element with an img-bottom key as sites to show+ # and generate a card item for each of them+ grid_items = []+ for item in safe_load(yaml_string):+ # remove parameters that are not needed for the card options+ title = item.pop("title", "")++ # build the content of the card using some extra parameters+ header = f"{item.pop('header')} \n^^^ \n" if "header" in item else ""+ image = f"}) \n" if "image" in item else ""+ content = f"{item.pop('content')} \n" if "content" in item else ""++ # optional parameter that influence all cards+ if "class-card" in self.options:+ item["class-card"] = self.options["class-card"]++ loc_options_str = "\n".join(f":{k}: {v}" for k, v in item.items()) + " \n"++ card = GRID_CARD.format(+ options=loc_options_str, content=header + image + content, title=title+ )+ grid_items.append(card)++ # Parse the template with Sphinx Design to create an output container+ # Prep the options for the template grid+ class_ = "gallery-directive" + f' {self.options.get("class-container", "")}'+ options = {"gutter": 2, "class-container": class_}+ options_str = "\n".join(f":{k}: {v}" for k, v in options.items())++ # Create the directive string for the grid+ grid_directive = TEMPLATE_GRID.format(+ columns=self.options.get("grid-columns", "1 2 3 4"),+ options=options_str,+ content="\n".join(grid_items),+ )++ # Parse content as a directive so Sphinx Design processes it+ container = nodes.container()+ self.state.nested_parse([grid_directive], 0, container)++ # Sphinx Design outputs a container too, so just use that+ return [container.children[0]]+++def setup(app: Sphinx) -> Dict[str, Any]:+ """Add custom configuration to sphinx app.++ Args:+ app: the Sphinx application++ Returns:+ the 2 parallel parameters set to ``True``.+ """+ app.add_directive("gallery-grid", GalleryGridDirective)++ return {+ "parallel_read_safe": True,+ "parallel_write_safe": True,+ }diff --git a/python/packages/autogen-core/docs/src/_static/custom.css b/python/packages/autogen-core/docs/src/_static/custom.cssnew file mode 100644index 000000000..9daae5861--- /dev/null+++ b/python/packages/autogen-core/docs/src/_static/custom.css@@ -0,0 +1,3 @@+.bd-links__title {+ display: none;+}diff --git a/python/packages/autogen-core/docs/src/_static/switcher.json b/python/packages/autogen-core/docs/src/_static/switcher.jsonnew file mode 100644index 000000000..b3c8d67dd--- /dev/null+++ b/python/packages/autogen-core/docs/src/_static/switcher.json@@ -0,0 +1,11 @@+[+ {+ "name": "v0.2 (stable)",+ "version": "0.2",+ "url": "https://microsoft.github.io/autogen/en/0.2/"+ },+ {+ "version": "dev",+ "url": "https://microsoft.github.io/autogen/en/dev/"+ }+]diff --git a/python/packages/autogen-core/docs/src/_templates/edit-this-page.html b/python/packages/autogen-core/docs/src/_templates/edit-this-page.htmlnew file mode 100644index 000000000..0254d1a2a--- /dev/null+++ b/python/packages/autogen-core/docs/src/_templates/edit-this-page.html@@ -0,0 +1,16 @@+{% if sourcename is defined and theme_use_edit_page_button and page_source_suffix %}+ {% set src = sourcename.split('.') %}+ <div class="tocsection editthispage">+ <a href="{{ to_main(get_edit_provider_and_url()[1]) }}">+ <i class="fa-solid fa-pencil"></i>+ {% set provider = get_edit_provider_and_url()[0] %}+ {% block edit_this_page_text %}+ {% if provider %}+ {% trans provider=provider %}Edit on {{ provider }}{% endtrans %}+ {% else %}+ {% trans %}Edit{% endtrans %}+ {% endif %}+ {% endblock %}+ </a>+ </div>+{% endif %}diff --git a/python/packages/autogen-core/docs/src/_templates/layout.html b/python/packages/autogen-core/docs/src/_templates/layout.htmlnew file mode 100644index 000000000..af41810c7--- /dev/null+++ b/python/packages/autogen-core/docs/src/_templates/layout.html@@ -0,0 +1,30 @@+{% extends "!layout.html" %}++{% block footer %}+<footer class="bd-footer">+ <div class="container">+ <div class="row">+ <div class="col-12 col-md-4 mb-4 mb-md-0">+ <h6>About</h5>+ <p>© 2024 Microsoft.</p>+ </div>+ <div class="col-6 col-md-4 mb-4 mb-md-0">+ <h6>Links</h5>+ <ul class="list-unstyled">+ <li><a href="https://go.microsoft.com/fwlink/?LinkId=521839">Privacy Policy</a> | <a href="https://go.microsoft.com/fwlink/?linkid=2259814">Consumer Health Privacy</a> </li>++ </ul>+ </div>+ <div class="col-6 col-md-4">+ <h6>Community</h5>+ <ul class="list-unstyled">+ <li>+ <a href="https://x.com/pyautogen" target="_blank">Twitter</a>+ </li>+ </ul>+ </div>+ </div>+ </div>+</footer>+{% endblock %}+diff --git a/python/packages/autogen-core/docs/src/conf.py b/python/packages/autogen-core/docs/src/conf.pyindex 8cfe7353c..8736932e7 100644--- a/python/packages/autogen-core/docs/src/conf.py+++ b/python/packages/autogen-core/docs/src/conf.py@@ -3,35 +3,53 @@# For the full list of built-in configuration values, see the documentation:# https://www.sphinx-doc.org/en/master/usage/configuration.html+import pydata_sphinx_theme+from sphinx.application import Sphinx+from typing import Any, Dict+from pathlib import Path+import sys# -- Project information -----------------------------------------------------# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information+project = "autogen_core"copyright = "2024, Microsoft"author = "Microsoft"+version = "0.2"+++sys.path.append(str(Path(".").resolve()))# -- General configuration ---------------------------------------------------# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configurationextensions = [+ "sphinx.ext.napoleon","sphinx.ext.autodoc","sphinx.ext.autosummary",- "sphinx.ext.napoleon",+ "sphinx.ext.todo",+ "sphinx.ext.viewcode",+ "sphinx.ext.intersphinx",+ "sphinx.ext.graphviz",+ "sphinx_design","sphinxcontrib.apidoc",+ "sphinx_copybutton",+ "_extension.gallery_directive","myst_nb",- "sphinx.ext.intersphinx",]+suppress_warnings = ["myst.header"]apidoc_module_dir = "../../src/autogen_core"-apidoc_output_dir = "reference"+apidoc_output_dir = "reference/python"apidoc_template_dir = "_apidoc_templates"apidoc_separate_modules = True+apidoc_toc_file = "index"apidoc_extra_args = ["--no-toc"]napoleon_custom_sections = [("Returns", "params_style")]apidoc_excluded_paths = ["./application/protos/"]-templates_path = []-exclude_patterns = ["reference/autogen_core.rst"]+templates_path = ["_templates"]+exclude_patterns = ["reference/python/autogen_core.rst"]autoclass_content = "init"@@ -44,18 +62,60 @@ nb_execution_timeout = 60myst_heading_anchors = 5+# -- Options for HTML output -------------------------------------------------# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-outputhtml_title = "AGNext"-html_theme = "furo"-html_static_path = []+html_theme = "pydata_sphinx_theme"+html_static_path = ["_static"]+html_css_files = ["custom.css"]+html_sidebars = {'packages/index': []}html_theme_options = {- "source_repository": "https://github.com/microsoft/agnext",- "source_branch": "main",- "source_directory": "python/packages/autogen-core/docs/src/",++ "header_links_before_dropdown": 4,+ "navbar_align": "left",+ "check_switcher": False,+ # "navbar_start": ["navbar-logo", "version-switcher"],+ # "switcher": {+ # "json_url": "/_static/switcher.json",+ # },+ "show_prev_next": False,+ ""+ "icon_links": [+ {+ "name": "Twitter",+ "url": "https://twitter.com/pyautogen",+ "icon": "fa-brands fa-twitter",+ },+ {+ "name": "GitHub",+ "url": "https://github.com/microsoft/agnext",+ "icon": "fa-brands fa-github",+ },+ {+ "name": "PyPI",+ "url": "https://pypi.org/project/autogen-core",+ "icon": "fa-custom fa-pypi",+ },+ {+ "name": "PyData",+ "url": "https://pydata.org",+ "icon": "fa-custom fa-pydata",+ },+ ],++}+++html_context = {+ 'display_github': True,+ "github_user": "microsoft",+ "github_repo": "agnext",+ "github_version": "main",+ "doc_path": "python/packages/autogen-core/docs/src/",}autodoc_default_options = {@@ -64,3 +124,40 @@ autodoc_default_options = {}intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}+++def setup_to_main(+ app: Sphinx, pagename: str, templatename: str, context, doctree+) -> None:+ """Add a function that jinja can access for returning an "edit this page" link pointing to `main`."""++ def to_main(link: str) -> str:+ """Transform "edit on github" links and make sure they always point to the main branch.++ Args:+ link: the link to the github edit interface++ Returns:+ the link to the tip of the main branch for the same file+ """+ links = link.split("/")+ idx = links.index("edit")+ return "/".join(links[: idx + 1]) + "/main/" + "/".join(links[idx + 2:])++ context["to_main"] = to_main+++def setup(app: Sphinx) -> Dict[str, Any]:+ """Add custom configuration to sphinx app.++ Args:+ app: the Sphinx application+ Returns:+ the 2 parallel parameters set to ``True``.+ """+ app.connect("html-page-context", setup_to_main)++ return {+ "parallel_read_safe": True,+ "parallel_write_safe": True,+ }diff --git a/python/packages/autogen-core/docs/src/index.md b/python/packages/autogen-core/docs/src/index.mdnew file mode 100644index 000000000..71b95fcc6--- /dev/null+++ b/python/packages/autogen-core/docs/src/index.md@@ -0,0 +1,79 @@+---+myst:+ html_meta:+ "description lang=en": |+ Top-level documentation for AGNext, a framework for building multi-agent applications with AI agents.+html_theme.sidebar_secondary.remove: false+---++# AGNext++AGNext is a OSS framework for developing intelligent applications using AI Agents patterns.+It offers an easy way to quickly build event-driven, distributed, scalable, resilient AI agent systems. Agents are developed by using the [Actor model](https://en.wikipedia.org/wiki/Actor_model). You can build and run your agent system locally and easily move to a distributed system in the cloud when you are ready.++Key features of AGNext are summarized below.++```{gallery-grid}+:grid-columns: 1 2 2 3++- header: "{fas}`network-wired;pst-color-primary` Asynchronous Messaging"+ content: "Agents communicate through asynchronous messages, enabling event-driven and request/response communication models."+- header: "{fas}`cube;pst-color-primary` Scalable & Distributed"+ content: "Enable complex scenarios with networks of agents across organizational boundaries."+- header: "{fas}`code;pst-color-primary` Multi-Language Support"+ content: "Python & Dotnet interoperating agents today, with more languages coming soon."+- header: "{fas}`globe;pst-color-primary` Modular & Extensible"+ content: "Highly customizable with features like custom agents, memory as a service, tools registry, and model library."+- header: "{fas}`puzzle-piece;pst-color-primary` Observable & Debuggable"+ content: "Easily trace and debug your agent systems."+- header: "{fas}`project-diagram;pst-color-primary` Event-Driven Architecture"+ content: "Build event-driven, distributed, scalable, and resilient AI agent systems."+```++<!--+Key features of AGNext include:++- Asynchronous messaging: Agents communicate with each other through asynchronous messages, enabling event-driven and request/response communication models.+- Scalable & Distributed: Enable complex scenarios with networks of agents across org boundaries+- Modular, extensible & highly customizable: E.g. custom agents, memory as a service, tools registry, model library+- x-lang support: Python & Dotnet interoperating agents today, others coming soon+- Observable, traceable & debuggable -->++```{seealso}+To start quickly, read the [Quick Start](user-guide/getting-started/quickstart) guide and follow the tutorial sections. To learn about the core concepts of AGNext, begin with [Agent and Multi-Agent Application](user-guide/core-concepts/agent-and-multi-agent-application).+```++```{toctree}+:maxdepth: 1+:hidden:++user-guide/index+```++<!-- ## Community++Information about the community that leads, supports, and develops AGNext.++```{toctree}+:maxdepth: 2++community/index+``` -->++```{toctree}+:maxdepth: 2+:hidden:+packages/index+```++```{toctree}+:maxdepth: 1+:hidden:+reference/index+```++<!-- ````{toctree}+:hidden:++Changelog <https://github.com/your-org/agnext/releases>+``` -->diff --git a/python/packages/autogen-core/docs/src/index.rst b/python/packages/autogen-core/docs/src/index.rstdeleted file mode 100644index ac0a73f5b..000000000--- a/python/packages/autogen-core/docs/src/index.rst+++ /dev/null@@ -1,76 +0,0 @@-AGNext---------AGNext is a framework for building multi-agent applications with AI agents.--At a high level, it provides a framework for inter-agent communication and a-suite of independent components for building and managing agents.-You can implement agents in-different programming languages and deploy them on different machines across organizational boundaries.-You can also implement agents using other agent frameworks and run them in AGNext.--To start quickly, read the `Quick Start <getting-started/quickstart.html>`_ and-follow the tutorial sections.--To learn about the core concepts of AGNext, read the sections starting-from `Agent and Multi-Agent Application <core-concepts/agent-and-multi-agent-application.html>`_.--.. toctree::- :caption: Core Concepts- :hidden:-- core-concepts/agent-and-multi-agent-application- core-concepts/architecture- core-concepts/application-stack- core-concepts/agent-identity-and-lifecycle- core-concepts/topic-and-subscription--.. toctree::- :caption: Getting started- :hidden:-- getting-started/installation- getting-started/quickstart- getting-started/agent-and-agent-runtime- getting-started/message-and-communication- getting-started/model-clients- getting-started/tools- getting-started/multi-agent-design-patterns- getting-started/group-chat- getting-started/reflection--.. toctree::- :caption: Guides- :hidden:-- guides/logging- guides/distributed-agent-runtime- guides/telemetry- guides/command-line-code-executors--.. toctree::- :caption: Cookbook- :hidden:-- cookbook/azure-openai-with-aad-auth- cookbook/termination-with-intervention- cookbook/extracting-results-with-an-agent- cookbook/openai-assistant-agent- cookbook/langgraph-agent- cookbook/llamaindex-agent---.. toctree::- :caption: Reference- :hidden:-- reference/autogen_core.components- reference/autogen_core.application- reference/autogen_core.base--.. toctree::- :caption: Other- :hidden:-- other/faqs- other/contributingdiff --git a/python/packages/autogen-core/docs/src/other/CONTRIBUTING.md b/python/packages/autogen-core/docs/src/other/CONTRIBUTING.mddeleted file mode 120000index 15d2819e4..000000000--- a/python/packages/autogen-core/docs/src/other/CONTRIBUTING.md+++ /dev/null@@ -1 +0,0 @@-../../../../../../CONTRIBUTING.md\ No newline at end of filediff --git a/python/packages/autogen-core/docs/src/packages/index.md b/python/packages/autogen-core/docs/src/packages/index.mdnew file mode 100644index 000000000..33ea20074--- /dev/null+++ b/python/packages/autogen-core/docs/src/packages/index.md@@ -0,0 +1,24 @@+---+myst:+ html_meta:+ "description lang=en": |+ AGNext packages provide a set of functionality for building multi-agent applications with AI agents.+html_theme.nosidebar: true+---++# Packages++AgNext offers a set of packages beginning with the `autogen-core` package. Each package is designed to provide a specific set of functionality.++```{gallery-grid}+:grid-columns: 1 2 2 3++- header: "{fas}`cube;pst-color-primary` AutoGen Core"+ content: "Implements the core functionality of the AGNext framework, providing basic building blocks for creating multi-agent systems. [PyPI](https://pypi.org/project/autogen-core/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-core) "++- header: "{fas}`users;pst-color-primary` TeamOne"+ content: "A generalist multi-agent softbot utilizing five agents to tackle intricate tasks involving multi-step planning and real-world actions. [PyPI](https://pypi.org/project/teamone/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/team-one) "++- header: "{fas}`chart-bar;pst-color-primary` AgBench"+ content: "AutoGenBench is a tool for repeatedly running pre-defined AutoGen tasks in tightly-controlled initial conditions. [PyPI](https://pypi.org/project/autogenbench/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/agbench) "+```diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.mdnew file mode 100644index 000000000..acac42e6a--- /dev/null+++ b/python/packages/autogen-core/docs/src/reference/index.md@@ -0,0 +1,19 @@+---+myst:+ html_meta:+ "description lang=en": |+ AGNext is a community-driven project. Learn how to get involved, contribute, and connect with the community.+---++# API Reference++This section contains the API reference for the AGNext core package.++```{toctree}+:caption: Python API Reference+:maxdepth: 1++python/autogen_core.components+python/autogen_core.application+python/autogen_core.base+```diff --git a/python/packages/autogen-core/docs/src/cookbook/azure-openai-with-aad-auth.md b/python/packages/autogen-core/docs/src/user-guide/cookbook/azure-openai-with-aad-auth.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/azure-openai-with-aad-auth.mdrename to python/packages/autogen-core/docs/src/user-guide/cookbook/azure-openai-with-aad-auth.mddiff --git a/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/extracting-results-with-an-agent.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynbrename to python/packages/autogen-core/docs/src/user-guide/cookbook/extracting-results-with-an-agent.ipynbdiff --git a/python/packages/autogen-core/docs/src/cookbook/langgraph-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/langgraph-agent.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/langgraph-agent.ipynbrename to python/packages/autogen-core/docs/src/user-guide/cookbook/langgraph-agent.ipynbdiff --git a/python/packages/autogen-core/docs/src/cookbook/llamaindex-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/llamaindex-agent.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/llamaindex-agent.ipynbrename to python/packages/autogen-core/docs/src/user-guide/cookbook/llamaindex-agent.ipynbdiff --git a/python/packages/autogen-core/docs/src/cookbook/openai-assistant-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/openai-assistant-agent.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/openai-assistant-agent.ipynbrename to python/packages/autogen-core/docs/src/user-guide/cookbook/openai-assistant-agent.ipynbdiff --git a/python/packages/autogen-core/docs/src/cookbook/termination-with-intervention.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/termination-with-intervention.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/cookbook/termination-with-intervention.ipynbrename to python/packages/autogen-core/docs/src/user-guide/cookbook/termination-with-intervention.ipynbdiff --git a/python/packages/autogen-core/docs/src/core-concepts/agent-and-multi-agent-application.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-and-multi-agent-application.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agent-and-multi-agent-application.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-and-multi-agent-application.mddiff --git a/python/packages/autogen-core/docs/src/core-concepts/agent-identity-and-lifecycle.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-identity-and-lifecycle.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agent-identity-and-lifecycle.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-identity-and-lifecycle.mddiff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-application-stack.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-application-stack.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agnext-application-stack.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-application-stack.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-distributed.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-distributed.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-distributed.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-distributed.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-standalone.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-standalone.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-standalone.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-standalone.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-code-gen-example.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-code-gen-example.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agnext-code-gen-example.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-code-gen-example.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-layers.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-layers.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/agnext-layers.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-layers.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/application-stack.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/application-stack.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/application-stack.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/application-stack.mddiff --git a/python/packages/autogen-core/docs/src/core-concepts/architecture.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/architecture.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/architecture.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/architecture.mddiff --git a/python/packages/autogen-core/docs/src/other/faqs.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/faqs.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/other/faqs.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/faqs.mddiff --git a/python/packages/autogen-core/docs/src/core-concepts/subscription.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/subscription.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/subscription.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/subscription.svgdiff --git a/python/packages/autogen-core/docs/src/core-concepts/topic-and-subscription.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/topic-and-subscription.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/topic-and-subscription.mdrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/topic-and-subscription.mddiff --git a/python/packages/autogen-core/docs/src/core-concepts/type-subscription.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/type-subscription.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/core-concepts/type-subscription.svgrename to python/packages/autogen-core/docs/src/user-guide/core-concepts/type-subscription.svgdiff --git a/python/packages/autogen-core/docs/src/getting-started/agent-and-agent-runtime.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/agent-and-agent-runtime.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/agent-and-agent-runtime.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/agent-and-agent-runtime.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/coder-reviewer-data-flow.svg b/python/packages/autogen-core/docs/src/user-guide/getting-started/coder-reviewer-data-flow.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/coder-reviewer-data-flow.svgrename to python/packages/autogen-core/docs/src/user-guide/getting-started/coder-reviewer-data-flow.svgdiff --git a/python/packages/autogen-core/docs/src/getting-started/group-chat.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/group-chat.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/group-chat.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/group-chat.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/installation.md b/python/packages/autogen-core/docs/src/user-guide/getting-started/installation.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/installation.mdrename to python/packages/autogen-core/docs/src/user-guide/getting-started/installation.mddiff --git a/python/packages/autogen-core/docs/src/getting-started/message-and-communication.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/message-and-communication.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/message-and-communication.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/message-and-communication.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/model-clients.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/model-clients.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/model-clients.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/model-clients.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/multi-agent-design-patterns.md b/python/packages/autogen-core/docs/src/user-guide/getting-started/multi-agent-design-patterns.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/multi-agent-design-patterns.mdrename to python/packages/autogen-core/docs/src/user-guide/getting-started/multi-agent-design-patterns.mddiff --git a/python/packages/autogen-core/docs/src/getting-started/quickstart.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/quickstart.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/quickstart.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/quickstart.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/reflection.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/reflection.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/reflection.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/reflection.ipynbdiff --git a/python/packages/autogen-core/docs/src/getting-started/tool-use-agent-cfg.svg b/python/packages/autogen-core/docs/src/user-guide/getting-started/tool-use-agent-cfg.svgsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/tool-use-agent-cfg.svgrename to python/packages/autogen-core/docs/src/user-guide/getting-started/tool-use-agent-cfg.svgdiff --git a/python/packages/autogen-core/docs/src/getting-started/tools.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/tools.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/getting-started/tools.ipynbrename to python/packages/autogen-core/docs/src/user-guide/getting-started/tools.ipynbdiff --git a/python/packages/autogen-core/docs/src/guides/command-line-code-executors.ipynb b/python/packages/autogen-core/docs/src/user-guide/guides/command-line-code-executors.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/guides/command-line-code-executors.ipynbrename to python/packages/autogen-core/docs/src/user-guide/guides/command-line-code-executors.ipynbdiff --git a/python/packages/autogen-core/docs/src/guides/distributed-agent-runtime.ipynb b/python/packages/autogen-core/docs/src/user-guide/guides/distributed-agent-runtime.ipynbsimilarity index 100%rename from python/packages/autogen-core/docs/src/guides/distributed-agent-runtime.ipynbrename to python/packages/autogen-core/docs/src/user-guide/guides/distributed-agent-runtime.ipynbdiff --git a/python/packages/autogen-core/docs/src/guides/logging.md b/python/packages/autogen-core/docs/src/user-guide/guides/logging.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/guides/logging.mdrename to python/packages/autogen-core/docs/src/user-guide/guides/logging.mddiff --git a/python/packages/autogen-core/docs/src/guides/telemetry.md b/python/packages/autogen-core/docs/src/user-guide/guides/telemetry.mdsimilarity index 100%rename from python/packages/autogen-core/docs/src/guides/telemetry.mdrename to python/packages/autogen-core/docs/src/user-guide/guides/telemetry.mddiff --git a/python/packages/autogen-core/docs/src/user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/index.mdnew file mode 100644index 000000000..4b6c4f356--- /dev/null+++ b/python/packages/autogen-core/docs/src/user-guide/index.md@@ -0,0 +1,82 @@+---+myst:+ html_meta:+ "description lang=en": |+ User Guide for AGNext, a framework for building multi-agent applications with AI agents.+---++# User Guide++AGNext is a flexible framework for building multi-agent systems. Begin with the [installation](getting-started/installation.md) guide to set up the framework on your machine. Then, follow the [quickstart](getting-started/quickstart) guide to get started with building your first multi-agent application.++```{danger}+This project and documentation is a work in progress. If you have any questions or need help, please reach out to us on GitHub.+```++```{toctree}+:caption: Getting Started+:maxdepth: 1+:hidden:++getting-started/installation+getting-started/quickstart+```++```{toctree}+:caption: Core Concepts+:maxdepth: 1+:hidden:+++core-concepts/agent-and-multi-agent-application+core-concepts/architecture+core-concepts/application-stack+core-concepts/agent-identity-and-lifecycle+core-concepts/topic-and-subscription+core-concepts/faqs++```++```{toctree}+:caption: Framework+:maxdepth: 1+:hidden:+getting-started/agent-and-agent-runtime+getting-started/message-and-communication+getting-started/model-clients+getting-started/tools++```++```{toctree}+:caption: Multi-Agent Design Patterns+:maxdepth: 1+:hidden:+getting-started/multi-agent-design-patterns+getting-started/group-chat+getting-started/reflection+```++```{toctree}+:caption: Cookbook+:maxdepth: 1+:hidden:+cookbook/azure-openai-with-aad-auth+cookbook/termination-with-intervention+cookbook/extracting-results-with-an-agent+cookbook/openai-assistant-agent+cookbook/langgraph-agent+cookbook/llamaindex-agent++```++```{toctree}+:caption: Guides+:maxdepth: 1+:hidden:+guides/logging+guides/distributed-agent-runtime+guides/telemetry+guides/command-line-code-executors++```diff --git a/python/packages/autogen-core/pyproject.toml b/python/packages/autogen-core/pyproject.tomlindex da9d71176..3e48b7af8 100644--- a/python/packages/autogen-core/pyproject.toml+++ b/python/packages/autogen-core/pyproject.toml@@ -63,6 +63,9 @@ dev-dependencies = ["types-docker","wikipedia","opentelemetry-sdk>=1.27.0",+ "sphinx-design",+ "pydata-sphinx-theme",+ "sphinx-copybutton",]@@ -99,3 +102,4 @@ mypy.sequence = [docs-build = "sphinx-build docs/src docs/build"docs-serve = "sphinx-autobuild --watch src docs/src docs/build"docs-check = "sphinx-build --fail-on-warning docs/src docs/build"+docs-clean = "rm -rf docs/build && rm -rf docs/src/reference/python/"diff --git a/python/uv.lock b/python/uv.lockindex ea0d59d01..608a8f2e9 100644--- a/python/uv.lock+++ b/python/uv.lock@@ -46,6 +46,18 @@ requirements = [{ name = "typer" },]+[[package]]+name = "accessible-pygments"+version = "0.0.5"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "pygments" },+]+sdist = { url = "https://files.pythonhosted.org/packages/bc/c1/bbac6a50d02774f91572938964c582fff4270eee73ab822a4aeea4d8b11b/accessible_pygments-0.0.5.tar.gz", hash = "sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872", size = 1377899 }+wheels = [+ { url = "https://files.pythonhosted.org/packages/8d/3f/95338030883d8c8b91223b4e21744b04d11b161a3ef117295d8241f50ab4/accessible_pygments-0.0.5-py3-none-any.whl", hash = "sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7", size = 1395903 },+]+[[package]]name = "agbench"version = "0.0.1a1"@@ -323,10 +335,13 @@ dev = [{ name = "opentelemetry-sdk" },{ name = "pip" },{ name = "polars" },+ { name = "pydata-sphinx-theme" },{ name = "python-dotenv" },{ name = "requests" },{ name = "sphinx" },{ name = "sphinx-autobuild" },+ { name = "sphinx-copybutton" },+ { name = "sphinx-design" },{ name = "sphinxcontrib-apidoc" },{ name = "tavily-python" },{ name = "textual" },@@ -376,10 +391,13 @@ dev = [{ name = "opentelemetry-sdk", specifier = ">=1.27.0" },{ name = "pip" },{ name = "polars" },+ { name = "pydata-sphinx-theme" },{ name = "python-dotenv" },{ name = "requests" },{ name = "sphinx" },{ name = "sphinx-autobuild" },+ { name = "sphinx-copybutton" },+ { name = "sphinx-design" },{ name = "sphinxcontrib-apidoc" },{ name = "tavily-python" },{ name = "textual" },@@ -3151,6 +3169,25 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/af/93/06d44e08277b3b818b75bd5f25e879d7693e4b7dd3505fde89916fcc9ca2/pydantic_core-2.20.1-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:254ec27fdb5b1ee60684f91683be95e5133c994cc54e86a0b0963afa25c8f8a6", size = 1914966 },]+[[package]]+name = "pydata-sphinx-theme"+version = "0.15.4"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "accessible-pygments" },+ { name = "babel" },+ { name = "beautifulsoup4" },+ { name = "docutils" },+ { name = "packaging" },+ { name = "pygments" },+ { name = "sphinx" },+ { name = "typing-extensions" },+]+sdist = { url = "https://files.pythonhosted.org/packages/67/ea/3ab478cccacc2e8ef69892c42c44ae547bae089f356c4b47caf61730958d/pydata_sphinx_theme-0.15.4.tar.gz", hash = "sha256:7762ec0ac59df3acecf49fd2f889e1b4565dbce8b88b2e29ee06fdd90645a06d", size = 2400673 }+wheels = [+ { url = "https://files.pythonhosted.org/packages/e7/d3/c622950d87a2ffd1654208733b5bd1c5645930014abed8f4c0d74863988b/pydata_sphinx_theme-0.15.4-py3-none-any.whl", hash = "sha256:2136ad0e9500d0949f96167e63f3e298620040aea8f9c74621959eda5d4cf8e6", size = 4640157 },+]+[[package]]name = "pydub"version = "0.25.1"@@ -4001,6 +4038,30 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/3c/dd/018ce05c532a22007ac58d4f45232514cd9d6dd0ee1dc374e309db830983/sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b", size = 22496 },]+[[package]]+name = "sphinx-copybutton"+version = "0.5.2"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "sphinx" },+]+sdist = { url = "https://files.pythonhosted.org/packages/fc/2b/a964715e7f5295f77509e59309959f4125122d648f86b4fe7d70ca1d882c/sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd", size = 23039 }+wheels = [+ { url = "https://files.pythonhosted.org/packages/9e/48/1ea60e74949eecb12cdd6ac43987f9fd331156388dcc2319b45e2ebb81bf/sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e", size = 13343 },+]++[[package]]+name = "sphinx-design"+version = "0.6.1"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "sphinx" },+]+sdist = { url = "https://files.pythonhosted.org/packages/2b/69/b34e0cb5336f09c6866d53b4a19d76c227cdec1bbc7ac4de63ca7d58c9c7/sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632", size = 2193689 }+wheels = [+ { url = "https://files.pythonhosted.org/packages/c6/43/65c0acbd8cc6f50195a3a1fc195c404988b15c67090e73c7a41a9f57d6bd/sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c", size = 2215338 },+]+[[package]]name = "sphinxcontrib-apidoc"version = "0.5.0"