Refactor autogen ext agents namespace (#4582)

* move magentic and openai assistant agents

* add import error messages

* add api docs ref files

* fix magentic rst path

* fix openai rst fname

* fix magentic rst title

* Add module

* rm

* fix some minor issues

---------

Co-authored-by: Leonardo Pinheiro <lpinheiro@microsoft.com>
Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

python/packages/autogen-core/docs/src/reference/index.md

@@ -39,6 +39,8 @@ python/autogen_core.logging
 :hidden:
 :caption: AutoGen Extensions
 
+python/autogen_ext.agents.magentic_one
+python/autogen_ext.agents.openai
 python/autogen_ext.agents.web_surfer
 python/autogen_ext.agents.file_surfer
 python/autogen_ext.agents.video_surfer

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.magentic_one.rst

@@ -0,0 +1,8 @@
+autogen\_ext.agents.magentic\_one
+=================================
+
+
+.. automodule:: autogen_ext.agents.magentic_one
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.openai.rst

@@ -0,0 +1,8 @@
+autogen\_ext.agents.openai
+================================
+
+
+.. automodule:: autogen_ext.agents.openai
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-ext/src/autogen_ext/agents/__init__.py

@@ -1,4 +0,0 @@
-from ._magentic_one_coder_agent import MagenticOneCoderAgent
-from ._openai_assistant_agent import OpenAIAssistantAgent
-
-__all__ = ["OpenAIAssistantAgent", "MagenticOneCoderAgent"]

python/packages/autogen-ext/src/autogen_ext/agents/magentic_one/__init__.py

@@ -0,0 +1,10 @@
+try:
+    from ._magentic_one_coder_agent import MagenticOneCoderAgent
+except ImportError as e:
+    raise ImportError(
+        "Dependencies for MagenticOneCoderAgent not found. "
+        "Please install autogen-ext with the 'magentic-one' extra: "
+        "pip install 'autogen-ext[magentic-one]'"
+    ) from e
+
+__all__ = ["MagenticOneCoderAgent"]

python/packages/autogen-ext/src/autogen_ext/agents/openai/__init__.py

@@ -0,0 +1,10 @@
+try:
+    from ._openai_assistant_agent import OpenAIAssistantAgent
+except ImportError as e:
+    raise ImportError(
+        "Dependencies for OpenAIAssistantAgent not found. "
+        "Please install autogen-ext with the 'openai' extra: "
+        "pip install 'autogen-ext[openai]'"
+    ) from e
+
+__all__ = ["OpenAIAssistantAgent"]

python/packages/autogen-ext/src/autogen_ext/agents/_openai_assistant_agent.py → python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_assistant_agent.py

@@ -39,6 +39,7 @@ from autogen_core.components.tools import FunctionTool, Tool
 _has_openai_dependencies: bool = True
 try:
     import aiofiles
+
     from openai import NOT_GIVEN
     from openai.resources.beta.threads import AsyncMessages, AsyncRuns, AsyncThreads
     from openai.types.beta.code_interpreter_tool_param import CodeInterpreterToolParam
@@ -50,6 +51,7 @@ except ImportError:
 
 if TYPE_CHECKING:
     import aiofiles
+
     from openai import NOT_GIVEN, AsyncClient, NotGiven
     from openai.pagination import AsyncCursorPage
     from openai.resources.beta.threads import AsyncMessages, AsyncRuns, AsyncThreads
@@ -98,27 +100,26 @@ class OpenAIAssistantAgent(BaseChatAgent):
     """An agent implementation that uses the OpenAI Assistant API to generate responses.
 
     This agent leverages the OpenAI Assistant API to create AI assistants with capabilities like:
-    - Code interpretation and execution
-    - File handling and search
-    - Custom function calling
-    - Multi-turn conversations
 
-    The agent maintains a thread of conversation and can use various tools including:
-    - Code interpreter: For executing code and working with files
-    - File search: For searching through uploaded documents
-    - Custom functions: For extending capabilities with user-defined tools
+    * Code interpretation and execution
+    * File handling and search
+    * Custom function calling
+    * Multi-turn conversations
 
-    .. note::
+    The agent maintains a thread of conversation and can use various tools including
 
-        The agent deletes all messages in the thread when :meth:`on_reset` is called.
+    * Code interpreter: For executing code and working with files
+    * File search: For searching through uploaded documents
+    * Custom functions: For extending capabilities with user-defined tools
 
     Key Features:
-    - Supports multiple file formats including code, documents, images
-    - Can handle up to 128 tools per assistant
-    - Maintains conversation context in threads
-    - Supports file uploads for code interpreter and search
-    - Vector store integration for efficient file search
-    - Automatic file parsing and embedding
+
+    * Supports multiple file formats including code, documents, images
+    * Can handle up to 128 tools per assistant
+    * Maintains conversation context in threads
+    * Supports file uploads for code interpreter and search
+    * Vector store integration for efficient file search
+    * Automatic file parsing and embedding
 
     Example:
         .. code-block:: python
@@ -126,7 +127,7 @@ class OpenAIAssistantAgent(BaseChatAgent):
             from openai import AsyncClient
             from autogen_core import CancellationToken
             import asyncio
-            from autogen_ext.agents import OpenAIAssistantAgent
+            from autogen_ext.agents.openai import OpenAIAssistantAgent
             from autogen_agentchat.messages import TextMessage
 
 

python/packages/autogen-ext/src/autogen_ext/agents/video_surfer/_video_surfer.py

@@ -31,9 +31,9 @@ class VideoSurfer(AssistantAgent):
 
     Example usage:
 
-        The following example demonstrates how to create an video surfing agent with
-        a model client and generate a response to a simple query about a local video
-        called video.mp4.
+    The following example demonstrates how to create an video surfing agent with
+    a model client and generate a response to a simple query about a local video
+    called video.mp4.
 
         .. code-block:: python
 
@@ -67,7 +67,7 @@ class VideoSurfer(AssistantAgent):
 
             asyncio.run(main())
 
-        The following example demonstrates how to create and use a VideoSurfer and UserProxyAgent with MagenticOneGroupChat.
+    The following example demonstrates how to create and use a VideoSurfer and UserProxyAgent with MagenticOneGroupChat.
 
         .. code-block:: python
 

python/packages/autogen-ext/src/autogen_ext/code_executors/azure/_azure_container_code_executor.py

@@ -51,10 +51,11 @@ class ACADynamicSessionsCodeExecutor(CodeExecutor):
 
         .. code-block:: bash
 
-            pip install 'autogen-ext[azure]==0.4.0.dev7'
+            pip install 'autogen-ext[azure]==0.4.0.dev8'
 
+    .. caution::
 
-    **This will execute LLM generated code on an Azure dynamic code container.**
+        **This will execute LLM generated code on an Azure dynamic code container.**
 
     The execution environment is similar to that of a jupyter notebook which allows for incremental code execution. The parameter functions are executed in order once at the beginning of each session. Each code block is then executed serially and in the order they are received. Each environment has a statically defined set of available packages which cannot be changed.
     Currently, attempting to use packages beyond what is available on the environment will result in an error. To get the list of supported packages, call the `get_available_packages` function.

python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py

@@ -59,7 +59,7 @@ class DockerCommandLineCodeExecutor(CodeExecutor):
 
         .. code-block:: bash
 
-            pip install 'autogen-ext[docker]==0.4.0.dev7'
+            pip install 'autogen-ext[docker]==0.4.0.dev8'
 
 
     The executor first saves each code block in a file in the working

python/packages/autogen-ext/tests/test_openai_assistant_agent.py

@@ -6,7 +6,7 @@ import pytest
 from autogen_agentchat.messages import TextMessage
 from autogen_core import CancellationToken
 from autogen_core.components.tools._base import BaseTool, Tool
-from autogen_ext.agents import OpenAIAssistantAgent
+from autogen_ext.agents.openai import OpenAIAssistantAgent
 from azure.identity import DefaultAzureCredential, get_bearer_token_provider
 from openai import AsyncAzureOpenAI
 from pydantic import BaseModel