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/_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/code_executors/azure/_azure_container_code_executor.py

@@ -51,8 +51,9 @@ 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.**
 

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