Skip to content

A programming framework for agentic AI

Add API docs for builtin clients (#4232)

Eric Zhu1bf5fbb67bb4
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 aa9f772d0..7faefa44c 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
@@ -851,6 +851,65 @@ class BaseOpenAIChatCompletionClient(ChatCompletionClient):
class OpenAIChatCompletionClient(BaseOpenAIChatCompletionClient):
+ """Chat completion client for OpenAI hosted models.
+
+ You can also use this client for OpenAI-compatible ChatCompletion endpoints.
+ **Using this client for non-OpenAI models is not tested or guaranteed.**
+
+ For non-OpenAI models, please first take a look at our `community extensions <https://microsoft.github.io/autogen/dev/user-guide/extensions-user-guide/index.html>`_
+ 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.
+ 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.**
+
+ To use this client, you must install the `openai` extension:
+
+ .. code-block:: bash
+
+ pip install 'autogen-ext[openai]==0.4.0.dev6'
+
+ The following code snippet shows how to use the client with an OpenAI model:
+
+ .. code-block:: python
+
+ from autogen_ext.models import OpenAIChatCompletionClient
+ from autogen_core.components.models import UserMessage
+
+ opneai_model_client = OpenAIChatCompletionClient(
+ model="gpt-4o-2024-08-06",
+ # api_key="sk-...", # Optional if you have an OPENAI_API_KEY environment variable set.
+ )
+
+ result = await opneai_model_client.create([UserMessage(content="What is the capital of France?", source="user")])
+ 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
+
+ from autogen_ext.models import OpenAIChatCompletionClient
+ from autogen_core.components.models import UserMessage
+
+ 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,
+ },
+ )
+
+ """
+
def __init__(self, **kwargs: Unpack[OpenAIClientConfiguration]):
if "model" not in kwargs:
raise ValueError("model is required for OpenAIChatCompletionClient")
@@ -877,6 +936,57 @@ class OpenAIChatCompletionClient(BaseOpenAIChatCompletionClient):
class AzureOpenAIChatCompletionClient(BaseOpenAIChatCompletionClient):
+ """Chat completion client for Azure OpenAI hosted models.
+
+ Args:
+ 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.**
+ 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. **Required for Azure models.**
+ 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.
+ max_retries (optional, int): The maximum number of retries to attempt.
+
+ To use this client, you must install the `azure` and `openai` extensions:
+
+ .. code-block:: bash
+
+ pip install 'autogen-ext[openai,azure]==0.4.0.dev6'
+
+ To use the client, you need to provide your deployment id, Azure Cognitive Services endpoint,
+ api version, and model capabilities.
+ For authentication, you can either provide an API key or an Azure Active Directory (AAD) token credential.
+
+ The following code snippet shows how to use AAD authentication.
+ The identity used must be assigned the `Cognitive Services OpenAI User <https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control#cognitive-services-openai-user>`_ role.
+
+ .. code-block:: python
+
+ from autogen_ext.models import AzureOpenAIChatCompletionClient
+ from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+
+ # Create the token provider
+ token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")
+
+ az_model_client = AzureOpenAIChatCompletionClient(
+ model="{your-azure-deployment}",
+ api_version="2024-06-01",
+ azure_endpoint="https://{your-custom-endpoint}.openai.azure.com/",
+ azure_ad_token_provider=token_provider, # Optional if you choose key-based authentication.
+ # api_key="sk-...", # For key-based authentication. `AZURE_OPENAI_API_KEY` environment variable can also be used instead.
+ model_capabilities={
+ "vision": True,
+ "function_calling": True,
+ "json_output": True,
+ },
+ )
+
+ 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.
+
+ """
+
def __init__(self, **kwargs: Unpack[AzureOpenAIClientConfiguration]):
if "model" not in kwargs:
raise ValueError("model is required for OpenAIChatCompletionClient")