Skip to content

A programming framework for agentic AI

Improve docs for model clients, add missing docs (#4930)

Jack Gerrits7b10f0ad1bb8
diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.md
index 2742ddbc3..3f1374643 100644
--- a/python/packages/autogen-core/docs/src/reference/index.md
+++ b/python/packages/autogen-core/docs/src/reference/index.md
@@ -45,6 +45,7 @@ python/autogen_ext.agents.web_surfer
python/autogen_ext.agents.file_surfer
python/autogen_ext.agents.video_surfer
python/autogen_ext.agents.video_surfer.tools
+python/autogen_ext.auth.azure
python/autogen_ext.teams.magentic_one
python/autogen_ext.models.openai
python/autogen_ext.models.replay
diff --git a/python/packages/autogen-core/docs/src/reference/python/autogen_ext.auth.azure.rst b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.auth.azure.rst
new file mode 100644
index 000000000..7d2739826
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.auth.azure.rst
@@ -0,0 +1,8 @@
+autogen\_ext.auth.azure
+=======================
+
+
+.. automodule:: autogen_ext.auth.azure
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/python/packages/autogen-core/docs/src/reference/python/autogen_ext.models.openai.rst b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.models.openai.rst
index 44703cb70..b74e4903f 100644
--- a/python/packages/autogen-core/docs/src/reference/python/autogen_ext.models.openai.rst
+++ b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.models.openai.rst
@@ -6,3 +6,4 @@ autogen\_ext.models.openai
:members:
:undoc-members:
:show-inheritance:
+ :member-order: bysource
diff --git a/python/packages/autogen-ext/src/autogen_ext/models/openai/__init__.py b/python/packages/autogen-ext/src/autogen_ext/models/openai/__init__.py
index bad5690e3..dbe2eb65e 100644
--- a/python/packages/autogen-ext/src/autogen_ext/models/openai/__init__.py
+++ b/python/packages/autogen-ext/src/autogen_ext/models/openai/__init__.py
@@ -1,12 +1,17 @@
-from ._openai_client import (
- AzureOpenAIChatCompletionClient,
- OpenAIChatCompletionClient,
+from ._openai_client import AzureOpenAIChatCompletionClient, OpenAIChatCompletionClient, BaseOpenAIChatCompletionClient
+from .config import (
+ AzureOpenAIClientConfigurationConfigModel,
+ OpenAIClientConfigurationConfigModel,
+ BaseOpenAIClientConfigurationConfigModel,
+ CreateArgumentsConfigModel,
)
-from .config import AzureOpenAIClientConfiguration, OpenAIClientConfiguration
__all__ = [
- "AzureOpenAIClientConfiguration",
- "AzureOpenAIChatCompletionClient",
- "OpenAIClientConfiguration",
"OpenAIChatCompletionClient",
+ "AzureOpenAIChatCompletionClient",
+ "BaseOpenAIChatCompletionClient",
+ "AzureOpenAIClientConfigurationConfigModel",
+ "OpenAIClientConfigurationConfigModel",
+ "BaseOpenAIClientConfigurationConfigModel",
+ "CreateArgumentsConfigModel",
]
diff --git a/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py b/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py
index 2975d19b6..31db4974b 100644
--- a/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py
+++ b/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py
@@ -907,52 +907,79 @@ class OpenAIChatCompletionClient(BaseOpenAIChatCompletionClient, Component[OpenA
for additional model clients.
Args:
- model (str): The model to use. **Required.**
- api_key (str): The API key to use. **Required if 'OPENAI_API_KEY' is not found in the environment variables.**
- timeout (optional, int): The timeout for the request in seconds.
- max_retries (optional, int): The maximum number of retries to attempt.
- organization_id (optional, str): The organization ID to use.
+ model (str): Which OpenAI model to use.
+ api_key (optional, str): The API key to use. **Required if 'OPENAI_API_KEY' is not found in the environment variables.**
+ organization (optional, str): The organization ID to use.
base_url (optional, str): The base URL to use. **Required if the model is not hosted on OpenAI.**
- model_capabilities (optional, ModelCapabilities): The capabilities of the model. **Required if the model name is not a valid OpenAI model.**
+ timeout: (optional, float): The timeout for the request in seconds.
+ max_retries (optional, int): The maximum number of retries to attempt.
+ model_info (optional, ModelInfo): The capabilities of the model. **Required if the model name is not a valid OpenAI model.**
+ frequency_penalty (optional, float):
+ logit_bias: (optional, dict[str, int]):
+ max_tokens (optional, int):
+ n (optional, int):
+ presence_penalty (optional, float):
+ response_format (optional, literal["json_object", "text"]):
+ seed (optional, int):
+ stop (optional, str | List[str]):
+ temperature (optional, float):
+ top_p (optional, float):
+ user (optional, str):
+
To use this client, you must install the `openai` extension:
- .. code-block:: bash
+ .. code-block:: bash
- pip install "autogen-ext[openai]==0.4.0.dev13"
+ pip install "autogen-ext[openai]==0.4.0.dev13"
The following code snippet shows how to use the client with an OpenAI model:
- .. code-block:: python
+ .. code-block:: python
- from autogen_ext.models.openai import OpenAIChatCompletionClient
- from autogen_core.models import UserMessage
+ from autogen_ext.models.openai import OpenAIChatCompletionClient
+ from autogen_core.models import UserMessage
- openai_client = OpenAIChatCompletionClient(
- model="gpt-4o-2024-08-06",
- # api_key="sk-...", # Optional if you have an OPENAI_API_KEY environment variable set.
- )
+ openai_client = OpenAIChatCompletionClient(
+ model="gpt-4o-2024-08-06",
+ # api_key="sk-...", # Optional if you have an OPENAI_API_KEY environment variable set.
+ )
- result = await openai_client.create([UserMessage(content="What is the capital of France?", source="user")]) # type: ignore
- print(result)
+ result = await openai_client.create([UserMessage(content="What is the capital of France?", source="user")]) # type: ignore
+ print(result)
To use the client with a non-OpenAI model, you need to provide the base URL of the model and the model capabilities:
- .. code-block:: python
+ .. code-block:: python
- from autogen_ext.models.openai import OpenAIChatCompletionClient
+ from autogen_ext.models.openai import OpenAIChatCompletionClient
- custom_model_client = OpenAIChatCompletionClient(
- model="custom-model-name",
- base_url="https://custom-model.com/reset/of/the/path",
- api_key="placeholder",
- model_capabilities={
- "vision": True,
- "function_calling": True,
- "json_output": True,
- },
- )
+ custom_model_client = OpenAIChatCompletionClient(
+ model="custom-model-name",
+ base_url="https://custom-model.com/reset/of/the/path",
+ api_key="placeholder",
+ model_capabilities={
+ "vision": True,
+ "function_calling": True,
+ "json_output": True,
+ },
+ )
+
+ To load the client from a configuration, you can use the `load_component` method:
+
+ .. code-block:: python
+
+ from autogen_core.models import ChatCompletionClient
+
+ config = {
+ "provider": "OpenAIChatCompletionClient",
+ "config": {"model": "gpt-4o", "api_key": "REPLACE_WITH_YOUR_API_KEY"},
+ }
+
+ client = ChatCompletionClient.load_component(config)
+
+ To view the full list of available configuration options, see the :py:class:`OpenAIClientConfigurationConfigModel` class.
"""
@@ -1007,15 +1034,29 @@ class AzureOpenAIChatCompletionClient(
"""Chat completion client for Azure OpenAI hosted models.
Args:
+
+ model (str): Which OpenAI model to use.
azure_endpoint (str): The endpoint for the Azure model. **Required for Azure models.**
- model (str): The deployment ID for the Azure model. **Required for Azure models.**
+ azure_deployment (str): Deployment name for the Azure model. **Required for Azure models.**
api_version (str): The API version to use. **Required for Azure models.**
azure_ad_token (str): The Azure AD token to use. Provide this or `azure_ad_token_provider` for token-based authentication.
- azure_ad_token_provider (Callable[[], Awaitable[str]]): The Azure AD token provider to use. Provide this or `azure_ad_token` for token-based authentication.
- model_capabilities (ModelCapabilities): The capabilities of the model if default resolved values are not correct.
+ azure_ad_token_provider (optional, Callable[[], Awaitable[str]] | AzureTokenProvider): The Azure AD token provider to use. Provide this or `azure_ad_token` for token-based authentication.
api_key (optional, str): The API key to use, use this if you are using key based authentication. It is optional if you are using Azure AD token based authentication or `AZURE_OPENAI_API_KEY` environment variable.
- timeout (optional, int): The timeout for the request in seconds.
+ timeout: (optional, float): The timeout for the request in seconds.
max_retries (optional, int): The maximum number of retries to attempt.
+ model_info (optional, ModelInfo): The capabilities of the model. **Required if the model name is not a valid OpenAI model.**
+ frequency_penalty (optional, float):
+ logit_bias: (optional, dict[str, int]):
+ max_tokens (optional, int):
+ n (optional, int):
+ presence_penalty (optional, float):
+ response_format (optional, literal["json_object", "text"]):
+ seed (optional, int):
+ stop (optional, str | List[str]):
+ temperature (optional, float):
+ top_p (optional, float):
+ user (optional, str):
+
To use this client, you must install the `azure` and `openai` extensions:
@@ -1047,6 +1088,39 @@ class AzureOpenAIChatCompletionClient(
# api_key="sk-...", # For key-based authentication. `AZURE_OPENAI_API_KEY` environment variable can also be used instead.
)
+ To load the client that uses identity based aith from a configuration, you can use the `load_component` method:
+
+ .. code-block:: python
+
+ from autogen_core.models import ChatCompletionClient
+
+ config = {
+ "provider": "AzureOpenAIChatCompletionClient",
+ "config": {
+ "model": "gpt-4o-2024-05-13",
+ "azure_endpoint": "https://{your-custom-endpoint}.openai.azure.com/",
+ "azure_deployment": "{your-azure-deployment}",
+ "api_version": "2024-06-01",
+ "azure_ad_token_provider": {
+ "provider": "autogen_ext.models.openai.AzureTokenProvider",
+ "config": {
+ "provider_kind": "DefaultAzureCredential",
+ "scopes": ["https://cognitiveservices.azure.com/.default"],
+ },
+ },
+ },
+ }
+
+ client = ChatCompletionClient.load_component(config)
+
+
+ To view the full list of available configuration options, see the :py:class:`AzureOpenAIClientConfigurationConfigModel` class.
+
+
+ .. note::
+
+ Right now only `DefaultAzureCredential` is supported with no additional args passed to it.
+
See `here <https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity#chat-completions>`_ for how to use the Azure client directly or for more info.
"""
diff --git a/python/packages/autogen-ext/src/autogen_ext/models/openai/config/__init__.py b/python/packages/autogen-ext/src/autogen_ext/models/openai/config/__init__.py
index 482af3a6f..a6b484780 100644
--- a/python/packages/autogen-ext/src/autogen_ext/models/openai/config/__init__.py
+++ b/python/packages/autogen-ext/src/autogen_ext/models/openai/config/__init__.py
@@ -52,17 +52,7 @@ class AzureOpenAIClientConfiguration(BaseOpenAIClientConfiguration, total=False)
azure_ad_token_provider: AsyncAzureADTokenProvider # Or AzureTokenProvider
-__all__ = [
- "AzureOpenAIClientConfiguration",
- "OpenAIClientConfiguration",
- "AzureOpenAIClientConfigurationConfigModel",
- "OpenAIClientConfigurationConfigModel",
-]
-
-
# Pydantic equivalents of the above TypedDicts
-
-
class CreateArgumentsConfigModel(BaseModel):
frequency_penalty: float | None = None
logit_bias: Dict[str, int] | None = None
diff --git a/python/samples/core_distributed-group-chat/_types.py b/python/samples/core_distributed-group-chat/_types.py
index cf5d8e752..033aa835b 100644
--- a/python/samples/core_distributed-group-chat/_types.py
+++ b/python/samples/core_distributed-group-chat/_types.py
@@ -4,7 +4,7 @@ from typing import Dict
from autogen_core.models import (
LLMMessage,
)
-from autogen_ext.models.openai import AzureOpenAIClientConfiguration
+from autogen_ext.models.openai.config import AzureOpenAIClientConfiguration
from pydantic import BaseModel
diff --git a/python/samples/core_distributed-group-chat/_utils.py b/python/samples/core_distributed-group-chat/_utils.py
index 2e329e745..9a84f30d0 100644
--- a/python/samples/core_distributed-group-chat/_utils.py
+++ b/python/samples/core_distributed-group-chat/_utils.py
@@ -5,7 +5,7 @@ from typing import Any, Iterable, Type
import yaml
from _types import AppConfig
from autogen_core import MessageSerializer, try_get_known_serializers_for_type
-from autogen_ext.models.openai import AzureOpenAIClientConfiguration
+from autogen_ext.models.openai.config import AzureOpenAIClientConfiguration
from azure.identity import DefaultAzureCredential, get_bearer_token_provider