A programming framework for agentic AI
Improve agentchat tutorial (#4233)
Eric Zhu4aec53c36f61
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.pyindex 7f5447fb5..7abe68132 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py@@ -9,7 +9,52 @@ from ._base_chat_agent import BaseChatAgentclass CodeExecutorAgent(BaseChatAgent):- """An agent that executes code snippets and report the results."""+ """An agent that extracts and executes code snippets found in received messages and returns the output.++ It is typically used within a team with another agent that generates code snippets to be executed.++ .. note::++ It is recommended that the `CodeExecutorAgent` agent uses a Docker container to execute code. This ensures that model-generated code is executed in an isolated environment. To use Docker, your environment must have Docker installed and running.+ Follow the installation instructions for `Docker <https://docs.docker.com/get-docker/>`_.++ In this example, we show how to set up a `CodeExecutorAgent` agent that uses the+ :py:class:`~autogen_ext.code_executors.DockerCommandLineCodeExecutor`+ to execute code snippets in a Docker container. The `work_dir` parameter indicates where all executed files are first saved locally before being executed in the Docker container.++ .. code-block:: python+++ from autogen_agentchat.agents import CodeExecutorAgent+ from autogen_ext.code_executors import DockerCommandLineCodeExecutor+++ async def run_code_executor_agent() -> None:+ # Create a code executor agent that uses a Docker container to execute code.+ code_executor = DockerCommandLineCodeExecutor(work_dir="coding")+ await code_executor.start()+ code_executor_agent = CodeExecutorAgent("code_executor", code_executor=code_executor)++ # Run the agent with a given code snippet.+ task = TextMessage(+ content='''Here is some code+ ```python+ print('Hello world')+ ```+ ''',+ source="user",+ )+ response = await code_executor_agent.on_messages([task], CancellationToken())+ print(response.chat_message)++ # Stop the code executor.+ await code_executor.stop()+++ # Use asyncio.run(run_code_executor_agent()) when running in a script.+ await run_code_executor_agent()++ """def __init__(self,diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynbindex b39c6c829..db3177f90 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb@@ -158,6 +158,28 @@"For more information on tool calling, refer to the documentation from [OpenAI](https://platform.openai.com/docs/guides/function-calling) and [Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)."]},+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Other Preset Agents\n",+ "\n",+ "The following preset agents are available:\n",+ "\n",+ "- {py:class}`~autogen_agentchat.agents.CodeExecutorAgent`: An agent that can execute code.\n",+ "- {py:class}`~autogen_ext.agents.MultimodalWebSurfer`: A multi-modal agent that can search the web and visit web pages for information."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Next Step\n",+ "\n",+ "Now we have discussed how to use the {py:class}`~autogen_agentchat.agents.AssistantAgent`,\n",+ "we can move on to the next section to learn how to use the teams feature of AgentChat."+ ]+ },{"cell_type": "markdown","metadata": {},@@ -186,246 +208,6 @@")\n","print(result) -->"]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "## CodeExecutorAgent\n",- "\n",- "The {py:class}`~autogen_agentchat.agents.CodeExecutorAgent`\n",- "preset extracts and executes code snippets found in received messages and returns the output. It is typically used within a team with another agent that generates code snippets to be executed.\n",- "\n",- "```{note}\n",- "It is recommended that the {py:class}`~autogen_agentchat.agents.CodeExecutorAgent` agent\n",- "uses a Docker container to execute code. This ensures that model-generated code is executed in an isolated environment. To use Docker, your environment must have Docker installed and running. \n",- "Follow the installation instructions for [Docker](https://docs.docker.com/get-docker/).\n",- "```\n",- "\n",- "In this example, we show how to set up a {py:class}`~autogen_agentchat.agents.CodeExecutorAgent` agent that uses the \n",- "{py:class}`~autogen_ext.code_executors.DockerCommandLineCodeExecutor` \n",- "to execute code snippets in a Docker container. The `work_dir` parameter indicates where all executed files are first saved locally before being executed in the Docker container."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {},- "outputs": [- {- "name": "stdout",- "output_type": "stream",- "text": [- "source='code_executor' models_usage=None content='Hello world\\n'\n"- ]- }- ],- "source": [- "from autogen_agentchat.agents import CodeExecutorAgent\n",- "from autogen_ext.code_executors import DockerCommandLineCodeExecutor\n",- "\n",- "\n",- "async def run_code_executor_agent() -> None:\n",- " # Create a code executor agent that uses a Docker container to execute code.\n",- " code_executor = DockerCommandLineCodeExecutor(work_dir=\"coding\")\n",- " await code_executor.start()\n",- " code_executor_agent = CodeExecutorAgent(\"code_executor\", code_executor=code_executor)\n",- "\n",- " # Run the agent with a given code snippet.\n",- " task = TextMessage(\n",- " content=\"\"\"Here is some code\n",- "```python\n",- "print('Hello world')\n",- "```\n",- "\"\"\",\n",- " source=\"user\",\n",- " )\n",- " response = await code_executor_agent.on_messages([task], CancellationToken())\n",- " print(response.chat_message)\n",- "\n",- " # Stop the code executor.\n",- " await code_executor.stop()\n",- "\n",- "\n",- "# Use asyncio.run(run_code_executor_agent()) when running in a script.\n",- "await run_code_executor_agent()"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "This example shows the agent executing a code snippet that prints \"Hello world\".\n",- "The agent then returns the output of the code execution."- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "## Build Your Own Agents\n",- "\n",- "You may have agents with behaviors that do not fall into a preset. \n",- "In such cases, you can build custom agents.\n",- "\n",- "All agents in AgentChat inherit from {py:class}`~autogen_agentchat.agents.BaseChatAgent` \n",- "class and implement the following abstract methods and attributes:\n",- "\n",- "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages`: The abstract method that defines the behavior of the agent in response to messages. This method is called when the agent is asked to provide a response in {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run`. It returns a {py:class}`~autogen_agentchat.base.Response` object.\n",- "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_reset`: The abstract method that resets the agent to its initial state. This method is called when the agent is asked to reset itself.\n",- "- {py:attr}`~autogen_agentchat.agents.BaseChatAgent.produced_message_types`: The list of possible {py:class}`~autogen_agentchat.messages.ChatMessage` message types the agent can produce in its response.\n",- "\n",- "Optionally, you can implement the the {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream` method to stream messages as they are generated by the agent. If this method is not implemented, the agent\n",- "uses the default implementation of {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream`\n",- "that calls the {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages` method and\n",- "yields all messages in the response."- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "### CounterDownAgent\n",- "\n",- "In this example, we create a simple agent that counts down from a given number to zero,\n",- "and produces a stream of messages with the current count."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {},- "outputs": [- {- "name": "stdout",- "output_type": "stream",- "text": [- "3...\n",- "2...\n",- "1...\n",- "Done!\n"- ]- }- ],- "source": [- "from typing import AsyncGenerator, List, Sequence\n",- "\n",- "from autogen_core.base import CancellationToken\n",- "from autogen_agentchat.agents import BaseChatAgent\n",- "from autogen_agentchat.base import Response\n",- "from autogen_agentchat.messages import AgentMessage, ChatMessage, TextMessage\n",- "\n",- "\n",- "class CountDownAgent(BaseChatAgent):\n",- " def __init__(self, name: str, count: int = 3):\n",- " super().__init__(name, \"A simple agent that counts down.\")\n",- " self._count = count\n",- "\n",- " @property\n",- " def produced_message_types(self) -> List[type[ChatMessage]]:\n",- " return [TextMessage]\n",- "\n",- " async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:\n",- " # Calls the on_messages_stream.\n",- " response: Response | None = None\n",- " async for message in self.on_messages_stream(messages, cancellation_token):\n",- " if isinstance(message, Response):\n",- " response = message\n",- " assert response is not None\n",- " return response\n",- "\n",- " async def on_messages_stream(\n",- " self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken\n",- " ) -> AsyncGenerator[AgentMessage | Response, None]:\n",- " inner_messages: List[AgentMessage] = []\n",- " for i in range(self._count, 0, -1):\n",- " msg = TextMessage(content=f\"{i}...\", source=self.name)\n",- " inner_messages.append(msg)\n",- " yield msg\n",- " # The response is returned at the end of the stream.\n",- " # It contains the final message and all the inner messages.\n",- " yield Response(chat_message=TextMessage(content=\"Done!\", source=self.name), inner_messages=inner_messages)\n",- "\n",- " async def on_reset(self, cancellation_token: CancellationToken) -> None:\n",- " pass\n",- "\n",- "\n",- "async def run_countdown_agent() -> None:\n",- " # Create a countdown agent.\n",- " countdown_agent = CountDownAgent(\"countdown\")\n",- "\n",- " # Run the agent with a given task and stream the response.\n",- " async for message in countdown_agent.on_messages_stream([], CancellationToken()):\n",- " if isinstance(message, Response):\n",- " print(message.chat_message.content)\n",- " else:\n",- " print(message.content)\n",- "\n",- "\n",- "# Use asyncio.run(run_countdown_agent()) when running in a script.\n",- "await run_countdown_agent()"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "### UserProxyAgent \n",- "\n",- "A common use case for building a custom agent is to create an agent that acts as a proxy for the user.\n",- "\n",- "In the example below we show how to implement a `UserProxyAgent` - an agent that asks the user to enter\n",- "some text through console and then returns that message as a response."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {},- "outputs": [- {- "name": "stdout",- "output_type": "stream",- "text": [- "I am glad to be here.\n"- ]- }- ],- "source": [- "import asyncio\n",- "from typing import List, Sequence\n",- "\n",- "from autogen_core.base import CancellationToken\n",- "from autogen_agentchat.base import Response\n",- "from autogen_agentchat.agents import BaseChatAgent\n",- "from autogen_agentchat.messages import ChatMessage, TextMessage\n",- "\n",- "\n",- "class UserProxyAgent(BaseChatAgent):\n",- " def __init__(self, name: str) -> None:\n",- " super().__init__(name, \"A human user.\")\n",- "\n",- " @property\n",- " def produced_message_types(self) -> List[type[ChatMessage]]:\n",- " return [TextMessage]\n",- "\n",- " async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:\n",- " user_input = await asyncio.get_event_loop().run_in_executor(None, input, \"Enter your response: \")\n",- " return Response(chat_message=TextMessage(content=user_input, source=self.name))\n",- "\n",- " async def on_reset(self, cancellation_token: CancellationToken) -> None:\n",- " pass\n",- "\n",- "\n",- "async def run_user_proxy_agent() -> None:\n",- " user_proxy_agent = UserProxyAgent(name=\"user_proxy_agent\")\n",- " response = await user_proxy_agent.on_messages([], CancellationToken())\n",- " print(response.chat_message.content)\n",- "\n",- "\n",- "# Use asyncio.run(run_user_proxy_agent()) when running in a script.\n",- "await run_user_proxy_agent()"- ]}],"metadata": {@@ -444,7 +226,7 @@"name": "python","nbconvert_exporter": "python","pygments_lexer": "ipython3",- "version": "3.12.5"+ "version": "3.11.5"}},"nbformat": 4,diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/custom-agents.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/custom-agents.ipynbnew file mode 100644index 000000000..7c90a0444--- /dev/null+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/custom-agents.ipynb@@ -0,0 +1,166 @@+{+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Custom Agents\n",+ "\n",+ "You may have agents with behaviors that do not fall into a preset. \n",+ "In such cases, you can build custom agents.\n",+ "\n",+ "All agents in AgentChat inherit from {py:class}`~autogen_agentchat.agents.BaseChatAgent` \n",+ "class and implement the following abstract methods and attributes:\n",+ "\n",+ "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages`: The abstract method that defines the behavior of the agent in response to messages. This method is called when the agent is asked to provide a response in {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run`. It returns a {py:class}`~autogen_agentchat.base.Response` object.\n",+ "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_reset`: The abstract method that resets the agent to its initial state. This method is called when the agent is asked to reset itself.\n",+ "- {py:attr}`~autogen_agentchat.agents.BaseChatAgent.produced_message_types`: The list of possible {py:class}`~autogen_agentchat.messages.ChatMessage` message types the agent can produce in its response.\n",+ "\n",+ "Optionally, you can implement the the {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream` method to stream messages as they are generated by the agent. If this method is not implemented, the agent\n",+ "uses the default implementation of {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream`\n",+ "that calls the {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages` method and\n",+ "yields all messages in the response."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## CounterDownAgent\n",+ "\n",+ "In this example, we create a simple agent that counts down from a given number to zero,\n",+ "and produces a stream of messages with the current count."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "from typing import AsyncGenerator, List, Sequence\n",+ "\n",+ "from autogen_agentchat.agents import BaseChatAgent\n",+ "from autogen_agentchat.base import Response\n",+ "from autogen_agentchat.messages import AgentMessage, ChatMessage, TextMessage\n",+ "from autogen_core.base import CancellationToken\n",+ "\n",+ "\n",+ "class CountDownAgent(BaseChatAgent):\n",+ " def __init__(self, name: str, count: int = 3):\n",+ " super().__init__(name, \"A simple agent that counts down.\")\n",+ " self._count = count\n",+ "\n",+ " @property\n",+ " def produced_message_types(self) -> List[type[ChatMessage]]:\n",+ " return [TextMessage]\n",+ "\n",+ " async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:\n",+ " # Calls the on_messages_stream.\n",+ " response: Response | None = None\n",+ " async for message in self.on_messages_stream(messages, cancellation_token):\n",+ " if isinstance(message, Response):\n",+ " response = message\n",+ " assert response is not None\n",+ " return response\n",+ "\n",+ " async def on_messages_stream(\n",+ " self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken\n",+ " ) -> AsyncGenerator[AgentMessage | Response, None]:\n",+ " inner_messages: List[AgentMessage] = []\n",+ " for i in range(self._count, 0, -1):\n",+ " msg = TextMessage(content=f\"{i}...\", source=self.name)\n",+ " inner_messages.append(msg)\n",+ " yield msg\n",+ " # The response is returned at the end of the stream.\n",+ " # It contains the final message and all the inner messages.\n",+ " yield Response(chat_message=TextMessage(content=\"Done!\", source=self.name), inner_messages=inner_messages)\n",+ "\n",+ " async def on_reset(self, cancellation_token: CancellationToken) -> None:\n",+ " pass\n",+ "\n",+ "\n",+ "async def run_countdown_agent() -> None:\n",+ " # Create a countdown agent.\n",+ " countdown_agent = CountDownAgent(\"countdown\")\n",+ "\n",+ " # Run the agent with a given task and stream the response.\n",+ " async for message in countdown_agent.on_messages_stream([], CancellationToken()):\n",+ " if isinstance(message, Response):\n",+ " print(message.chat_message.content)\n",+ " else:\n",+ " print(message.content)\n",+ "\n",+ "\n",+ "# Use asyncio.run(run_countdown_agent()) when running in a script.\n",+ "await run_countdown_agent()"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## UserProxyAgent \n",+ "\n",+ "A common use case for building a custom agent is to create an agent that acts as a proxy for the user.\n",+ "\n",+ "In the example below we show how to implement a `UserProxyAgent` - an agent that asks the user to enter\n",+ "some text through console and then returns that message as a response."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "import asyncio\n",+ "from typing import List, Sequence\n",+ "\n",+ "from autogen_agentchat.agents import BaseChatAgent\n",+ "from autogen_agentchat.base import Response\n",+ "from autogen_agentchat.messages import ChatMessage\n",+ "from autogen_core.base import CancellationToken\n",+ "\n",+ "\n",+ "class UserProxyAgent(BaseChatAgent):\n",+ " def __init__(self, name: str) -> None:\n",+ " super().__init__(name, \"A human user.\")\n",+ "\n",+ " @property\n",+ " def produced_message_types(self) -> List[type[ChatMessage]]:\n",+ " return [TextMessage]\n",+ "\n",+ " async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:\n",+ " user_input = await asyncio.get_event_loop().run_in_executor(None, input, \"Enter your response: \")\n",+ " return Response(chat_message=TextMessage(content=user_input, source=self.name))\n",+ "\n",+ " async def on_reset(self, cancellation_token: CancellationToken) -> None:\n",+ " pass\n",+ "\n",+ "\n",+ "async def run_user_proxy_agent() -> None:\n",+ " user_proxy_agent = UserProxyAgent(name=\"user_proxy_agent\")\n",+ " response = await user_proxy_agent.on_messages([], CancellationToken())\n",+ " print(response.chat_message.content)\n",+ "\n",+ "\n",+ "# Use asyncio.run(run_user_proxy_agent()) when running in a script.\n",+ "await run_user_proxy_agent()"+ ]+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": ".venv",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "name": "python",+ "version": "3.11.5"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2+}diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.mdindex d8a4d8559..fa0ed5f6c 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.md+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.md@@ -46,6 +46,12 @@ A smart team that uses a model-based strategy and custom selector.A dynamic team that uses handoffs to pass tasks between agents.:::+:::{grid-item-card} {fas}`users;pst-color-primary` Custom Agents+:link: ./custom-agents.html++How to build custom agents.+:::+::::```{toctree}@@ -58,4 +64,5 @@ teamsselector-group-chatswarmtermination+custom-agents```diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynbindex 80c9c8482..2adc862e5 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynb@@ -1,181 +1,191 @@{- "cells": [- {- "cell_type": "markdown",- "metadata": {},- "source": [- "# Models\n",- "\n",- "In many cases, agents need access to model services such as OpenAI, Azure OpenAI, and local models.\n",- "AgentChat utilizes model clients provided by the\n",- "[`autogen-ext`](../../core-user-guide/framework/model-clients.ipynb) package."- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "## OpenAI\n",- "\n",- "To access OpenAI models, you need to install the `openai` extension to use the {py:class}`~autogen_ext.models.OpenAIChatCompletionClient`."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {- "vscode": {- "languageId": "shellscript"- }- },- "outputs": [],- "source": [- "pip install 'autogen-ext[openai]==0.4.0.dev6'"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "You will also need to obtain an [API key](https://platform.openai.com/account/api-keys) from OpenAI."- ]- },- {- "cell_type": "code",- "execution_count": 10,- "metadata": {},- "outputs": [],- "source": [- "from autogen_ext.models import OpenAIChatCompletionClient\n",- "\n",- "opneai_model_client = OpenAIChatCompletionClient(\n",- " model=\"gpt-4o-2024-08-06\",\n",- " # api_key=\"sk-...\", # Optional if you have an OPENAI_API_KEY environment variable set.\n",- ")"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "To test the model client, you can use the following code:"- ]- },- {- "cell_type": "code",- "execution_count": 11,- "metadata": {},- "outputs": [- {- "name": "stdout",- "output_type": "stream",- "text": [- "CreateResult(finish_reason='stop', content='The capital of France is Paris.', usage=RequestUsage(prompt_tokens=15, completion_tokens=7), cached=False, logprobs=None)\n"- ]- }- ],- "source": [- "from autogen_core.components.models import UserMessage\n",- "\n",- "result = await opneai_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",- "print(result)"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "## Azure OpenAI\n",- "\n",- "Install the `azure` and `openai` extensions to use the {py:class}`~autogen_ext.models.AzureOpenAIChatCompletionClient`."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {- "vscode": {- "languageId": "shellscript"- }- },- "outputs": [],- "source": [- "pip install 'autogen-ext[openai,azure]==0.4.0.dev6'"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "To use the client, you need to provide your deployment id, Azure Cognitive Services endpoint, api version, and model capabilities.\n",- "For authentication, you can either provide an API key or an Azure Active Directory (AAD) token credential.\n",- "\n",- "The following code snippet shows how to use AAD authentication.\n",- "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."- ]- },- {- "cell_type": "code",- "execution_count": null,- "metadata": {},- "outputs": [],- "source": [- "from autogen_ext.models import AzureOpenAIChatCompletionClient\n",- "from azure.identity import DefaultAzureCredential, get_bearer_token_provider\n",- "\n",- "# Create the token provider\n",- "token_provider = get_bearer_token_provider(DefaultAzureCredential(), \"https://cognitiveservices.azure.com/.default\")\n",- "\n",- "az_model_client = AzureOpenAIChatCompletionClient(\n",- " model=\"{your-azure-deployment}\",\n",- " api_version=\"2024-06-01\",\n",- " azure_endpoint=\"https://{your-custom-endpoint}.openai.azure.com/\",\n",- " azure_ad_token_provider=token_provider, # Optional if you choose key-based authentication.\n",- " # api_key=\"sk-...\", # For key-based authentication.\n",- " model_capabilities={\n",- " \"vision\": True,\n",- " \"function_calling\": True,\n",- " \"json_output\": True,\n",- " },\n",- ")"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "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."- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "## Local Models\n",- "\n",- "We are working on it. Stay tuned!"- ]- }- ],- "metadata": {- "kernelspec": {- "display_name": ".venv",- "language": "python",- "name": "python3"- },- "language_info": {- "codemirror_mode": {- "name": "ipython",- "version": 3- },- "file_extension": ".py",- "mimetype": "text/x-python",- "name": "python",- "nbconvert_exporter": "python",- "pygments_lexer": "ipython3",- "version": "3.11.5"- }- },- "nbformat": 4,- "nbformat_minor": 2+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Models\n",+ "\n",+ "In many cases, agents need access to model services such as OpenAI, Azure OpenAI, and local models.\n",+ "AgentChat utilizes model clients provided by the\n",+ "[`autogen-ext`](../../core-user-guide/framework/model-clients.ipynb) package."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## OpenAI\n",+ "\n",+ "To access OpenAI models, you need to install the `openai` extension to use the {py:class}`~autogen_ext.models.OpenAIChatCompletionClient`."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {+ "vscode": {+ "languageId": "shellscript"+ }+ },+ "outputs": [],+ "source": [+ "pip install 'autogen-ext[openai]==0.4.0.dev6'"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "You will also need to obtain an [API key](https://platform.openai.com/account/api-keys) from OpenAI."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 10,+ "metadata": {},+ "outputs": [],+ "source": [+ "from autogen_ext.models import OpenAIChatCompletionClient\n",+ "\n",+ "opneai_model_client = OpenAIChatCompletionClient(\n",+ " model=\"gpt-4o-2024-08-06\",\n",+ " # api_key=\"sk-...\", # Optional if you have an OPENAI_API_KEY environment variable set.\n",+ ")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "To test the model client, you can use the following code:"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 11,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "CreateResult(finish_reason='stop', content='The capital of France is Paris.', usage=RequestUsage(prompt_tokens=15, completion_tokens=7), cached=False, logprobs=None)\n"+ ]+ }+ ],+ "source": [+ "from autogen_core.components.models import UserMessage\n",+ "\n",+ "result = await opneai_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",+ "print(result)"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "```{note}\n",+ "You can use this client with models hosted on OpenAI-compatible endpoints, however, we have not tested this functionality.\n",+ "See {py:class}`~autogen_ext.models.OpenAIChatCompletionClient` for more information.\n",+ "```"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Azure OpenAI\n",+ "\n",+ "Install the `azure` and `openai` extensions to use the {py:class}`~autogen_ext.models.AzureOpenAIChatCompletionClient`."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {+ "vscode": {+ "languageId": "shellscript"+ }+ },+ "outputs": [],+ "source": [+ "pip install 'autogen-ext[openai,azure]==0.4.0.dev6'"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "To use the client, you need to provide your deployment id, Azure Cognitive Services endpoint, api version, and model capabilities.\n",+ "For authentication, you can either provide an API key or an Azure Active Directory (AAD) token credential.\n",+ "\n",+ "The following code snippet shows how to use AAD authentication.\n",+ "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."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "from autogen_ext.models import AzureOpenAIChatCompletionClient\n",+ "from azure.identity import DefaultAzureCredential, get_bearer_token_provider\n",+ "\n",+ "# Create the token provider\n",+ "token_provider = get_bearer_token_provider(DefaultAzureCredential(), \"https://cognitiveservices.azure.com/.default\")\n",+ "\n",+ "az_model_client = AzureOpenAIChatCompletionClient(\n",+ " model=\"{your-azure-deployment}\",\n",+ " api_version=\"2024-06-01\",\n",+ " azure_endpoint=\"https://{your-custom-endpoint}.openai.azure.com/\",\n",+ " azure_ad_token_provider=token_provider, # Optional if you choose key-based authentication.\n",+ " # api_key=\"sk-...\", # For key-based authentication.\n",+ " model_capabilities={\n",+ " \"vision\": True,\n",+ " \"function_calling\": True,\n",+ " \"json_output\": True,\n",+ " },\n",+ ")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "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."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Local Models\n",+ "\n",+ "We are working on it. Stay tuned!"+ ]+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": ".venv",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "codemirror_mode": {+ "name": "ipython",+ "version": 3+ },+ "file_extension": ".py",+ "mimetype": "text/x-python",+ "name": "python",+ "nbconvert_exporter": "python",+ "pygments_lexer": "ipython3",+ "version": "3.11.5"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2}diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynbindex 8d001f897..0b5af2088 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb@@ -281,7 +281,7 @@"outputs": [],"source": ["from autogen_agentchat.agents import AssistantAgent\n",- "from autogen_agentchat.task import MaxMessageTermination, TextMentionTermination, Console\n",+ "from autogen_agentchat.task import Console, MaxMessageTermination, TextMentionTermination\n","from autogen_agentchat.teams import RoundRobinGroupChat\n","from autogen_ext.models import OpenAIChatCompletionClient\n","\n",diff --git a/python/packages/autogen-core/src/autogen_core/components/tools/_base.py b/python/packages/autogen-core/src/autogen_core/components/tools/_base.pyindex e9d8d2aa5..eb6a2067e 100644--- a/python/packages/autogen-core/src/autogen_core/components/tools/_base.py+++ b/python/packages/autogen-core/src/autogen_core/components/tools/_base.py@@ -1,7 +1,7 @@import jsonfrom abc import ABC, abstractmethodfrom collections.abc import Sequence-from typing import Any, Dict, Generic, Mapping, Protocol, Type, TypedDict, TypeVar, runtime_checkable, cast+from typing import Any, Dict, Generic, Mapping, Protocol, Type, TypedDict, TypeVar, cast, runtime_checkableimport jsonreffrom pydantic import BaseModeldiff --git a/python/packages/autogen-core/tests/test_tools.py b/python/packages/autogen-core/tests/test_tools.pyindex 867fd012d..70ec08469 100644--- a/python/packages/autogen-core/tests/test_tools.py+++ b/python/packages/autogen-core/tests/test_tools.py@@ -1,12 +1,12 @@import inspectfrom typing import Annotated, List-from autogen_core.components.tools._base import ToolSchemaimport pytestfrom autogen_core.base import CancellationTokenfrom autogen_core.components._function_utils import get_typed_signaturefrom autogen_core.components.models._openai_client import convert_toolsfrom autogen_core.components.tools import BaseTool, FunctionTool+from autogen_core.components.tools._base import ToolSchemafrom pydantic import BaseModel, Field, model_serializerfrom pydantic_core import PydanticUndefined