A programming framework for agentic AI
Add tutorial index page; improve installation pages; improve Core tutorial to mention how to use AgentChat agent in Core. (#4950)
Eric Zhu903305e81028
diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.mdindex 46f526c6c..9754bd8ca 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md@@ -31,19 +31,19 @@ How to install AgentChatBuild your first agent:::-:::{grid-item-card} {fas}`graduation-cap;pst-color-primary` Tutorial-:link: ./tutorial/models.html+:::{grid-item-card} {fas}`school;pst-color-primary` Tutorial+:link: ./tutorial/index.htmlStep-by-step guide to using AgentChat, learn about agents, teams, and more:::-:::{grid-item-card} {fas}`book;pst-color-primary` Selector Group Chat+:::{grid-item-card} {fas}`sitemap;pst-color-primary` Selector Group Chat:link: ./selector-group-chat.htmlMulti-agent coordination through a shared context and centralized, customizable selector:::-:::{grid-item-card} {fas}`book;pst-color-primary` Swarm+:::{grid-item-card} {fas}`dove;pst-color-primary` Swarm:link: ./swarm.htmlMulti-agent coordination through a shared context and localized, tool-based selector@@ -82,6 +82,7 @@ migration-guide:hidden::caption: Tutorial+tutorial/indextutorial/modelstutorial/messagestutorial/agentsdiff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/installation.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/installation.mdindex ce6fecb0b..b55fcccd5 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/installation.md+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/installation.md@@ -38,7 +38,7 @@ deactivateCreate and activate:```bash-conda create -n autogen python=3.10+conda create -n autogen python=3.12conda activate autogen```@@ -77,15 +77,8 @@ extensions:pip install "autogen-ext[openai]==0.4.0.dev13"```-## Install Docker for Code Execution+If you are using Azure OpenAI with AAD authentication, you need to install the following:-We recommend using Docker for code execution.-To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/).--A simple example of how to use Docker for code execution is shown below:--<!-- ```{include} stocksnippet.md--``` -->--To learn more about agents that execute code, see the [agents tutorial](./tutorial/agents.ipynb).+```bash+pip install "autogen-ext[azure]==0.4.0.dev13"+```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.mdnew file mode 100644index 000000000..abb8bc72f--- /dev/null+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.md@@ -0,0 +1,72 @@+---+myst:+ html_meta:+ "description lang=en": |+ Tutorial for AgentChat, a high-level API for AutoGen+---++# Introduction++This tutorial provides a step-by-step guide to using AgentChat.+Make sure you have first followed the [installation instructions](../installation.md)+to prepare your environment.++At any point you are stuck, feel free to ask for help on+[GitHub Discussions](https://github.com/microsoft/autogen/discussions)+or [Discord](https://aka.ms/autogen-discord).++```{note}+If you are coming from AutoGen v0.2, please read the [migration guide](../migration-guide.md).+```++::::{grid} 2 2 2 2+:gutter: 3++:::{grid-item-card} {fas}`brain;pst-color-primary` Models+:link: ./models.html++How to use LLM model clients+:::++:::{grid-item-card} {fas}`envelope;pst-color-primary` Messages+:link: ./messages.html++Understand the message types+:::++:::{grid-item-card} {fas}`robot;pst-color-primary` Agents+:link: ./agents.html++Work with AgentChat agents and get started with {py:class}`~autogen_agentchat.agents.AssistantAgent`+:::++:::{grid-item-card} {fas}`sitemap;pst-color-primary` Teams+:link: ./teams.html++Work with teams of agents and get started with {py:class}`~autogen_agentchat.teams.RoundRobinGroupChat`.+:::++:::{grid-item-card} {fas}`person-chalkboard;pst-color-primary` Human-in-the-Loop+:link: ./human-in-the-loop.html++Best practices for providing feedback to a team+:::++:::{grid-item-card} {fas}`circle-stop;pst-color-primary` Termination+:link: ./termination.html++Control a team using termination conditions+:::++:::{grid-item-card} {fas}`code;pst-color-primary` Custom Agents+:link: ./custom-agents.html++Create your own agents+:::++:::{grid-item-card} {fas}`database;pst-color-primary` Managing State+:link: ./state.html++Save and load agents and teams for persistent sessions+:::+::::diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/agent-and-agent-runtime.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/agent-and-agent-runtime.ipynbindex b704944b8..2c1b9179b 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/agent-and-agent-runtime.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/agent-and-agent-runtime.ipynb@@ -7,9 +7,8 @@"# Agent and Agent Runtime\n","\n","In this and the following section, we focus on the core concepts of AutoGen:\n",- "agents, agent runtime, messages, and communication.\n",- "You will not find any AI models or tools here, just the foundational\n",- "building blocks for building multi-agent applications.\n",+ "agents, agent runtime, messages, and communication -- \n",+ "the foundational building blocks for an multi-agent applications.\n","\n","```{note}\n","The Core API is designed to be unopinionated and flexible. So at times, you\n",@@ -25,22 +24,31 @@"cell_type": "markdown","metadata": {},"source": [- "An agent in AutoGen is an entity defined by the base class {py:class}`autogen_core.Agent`.\n",- "It has a unique identifier of the type {py:class}`autogen_core.AgentId`,\n",- "a metadata dictionary of the type {py:class}`autogen_core.AgentMetadata`,\n",+ "An agent in AutoGen is an entity defined by the base interface {py:class}`~autogen_core.Agent`.\n",+ "It has a unique identifier of the type {py:class}`~autogen_core.AgentId`,\n",+ "a metadata dictionary of the type {py:class}`~autogen_core.AgentMetadata`.\n","\n",- "and method for handling messages {py:meth}`autogen_core.BaseAgent.on_message_impl`. In most cases, you can subclass your agents from higher level class {py:class}`autogen_core.RoutedAgent` which enables you to route messages to corresponding message handler specified with {py:meth}`autogen_core.message_handler` decorator and proper type hint for the `message` variable.\n",+ "In most cases, you can subclass your agents from higher level class {py:class}`~autogen_core.RoutedAgent` which enables you to route messages to corresponding message handler specified with {py:meth}`~autogen_core.message_handler` decorator and proper type hint for the `message` variable.\n","An agent runtime is the execution environment for agents in AutoGen.\n",+ "\n","Similar to the runtime environment of a programming language,\n","an agent runtime provides the necessary infrastructure to facilitate communication\n","between agents, manage agent lifecycles, enforce security boundaries, and support monitoring and\n","debugging.\n",+ "\n","For local development, developers can use {py:class}`~autogen_core.SingleThreadedAgentRuntime`,\n","which can be embedded in a Python application.\n","\n","```{note}\n","Agents are not directly instantiated and managed by application code.\n","Instead, they are created by the runtime when needed and managed by the runtime.\n",+ "\n",+ "If you are already familiar with [AgentChat](../../agentchat-user-guide/index.md),\n",+ "it is important to note that AgentChat's agents such as\n",+ "{py:class}`~autogen_agentchat.agents.AssistantAgent` are created by application \n",+ "and thus not directly managed by the runtime. To use an AgentChat agent in Core,\n",+ "you need to create a wrapper Core agent that delegates messages to the AgentChat agent\n",+ "and let the runtime manage the wrapper agent.\n","```"]},@@ -59,7 +67,7 @@},{"cell_type": "code",- "execution_count": 1,+ "execution_count": 11,"metadata": {},"outputs": [],"source": [@@ -79,7 +87,7 @@"\n"," @message_handler\n"," async def handle_my_message_type(self, message: MyMessageType, ctx: MessageContext) -> None:\n",- " print(f\"Received message: {message.content}\") # type: ignore"+ " print(f\"{self.id.type} received message: {message.content}\")"]},{@@ -90,6 +98,55 @@"See the next section on [message and communication](./message-and-communication.ipynb)."]},+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Using an AgentChat Agent\n",+ "\n",+ "If you have an [AgentChat](../../agentchat-user-guide/index.md) agent and want to use it in the Core API, you can create\n",+ "a wrapper {py:class}`~autogen_core.RoutedAgent` that delegates messages to the AgentChat agent.\n",+ "The following example shows how to create a wrapper agent for the {py:class}`~autogen_agentchat.agents.AssistantAgent`\n",+ "in AgentChat."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 12,+ "metadata": {},+ "outputs": [],+ "source": [+ "from autogen_agentchat.agents import AssistantAgent\n",+ "from autogen_agentchat.messages import TextMessage\n",+ "from autogen_ext.models.openai import OpenAIChatCompletionClient\n",+ "\n",+ "\n",+ "class MyAssistant(RoutedAgent):\n",+ " def __init__(self, name: str) -> None:\n",+ " super().__init__(name)\n",+ " model_client = OpenAIChatCompletionClient(model=\"gpt-4o\")\n",+ " self._delegate = AssistantAgent(name, model_client=model_client)\n",+ "\n",+ " @message_handler\n",+ " async def handle_my_message_type(self, message: MyMessageType, ctx: MessageContext) -> None:\n",+ " print(f\"{self.id.type} received message: {message.content}\")\n",+ " response = await self._delegate.on_messages(\n",+ " [TextMessage(content=message.content, source=\"user\")], ctx.cancellation_token\n",+ " )\n",+ " print(f\"{self.id.type} responded: {response.chat_message.content}\")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "For how to use model client, see the [Model Client](./model-clients.ipynb) section.\n",+ "\n",+ "Since the Core API is unopinionated,\n",+ "you are not required to use the AgentChat API to use the Core API.\n",+ "You can implement your own agents or use another agent framework."+ ]+ },{"cell_type": "markdown","metadata": {},@@ -106,7 +163,7 @@"when they are needed.\n","\n","Agent type ({py:class}`~autogen_core.AgentType`) is not the same as the agent class. In this example,\n",- "the agent type is `AgentType(\"my_agent\")` and the agent class is the Python class `MyAgent`.\n",+ "the agent type is `AgentType(\"my_agent\")` or `AgentType(\"my_assistant\")` and the agent class is the Python class `MyAgent` or `MyAssistantAgent`.\n","The factory function is expected to return an instance of the agent class \n","on which the {py:meth}`~autogen_core.BaseAgent.register` class method is invoked.\n","Read [Agent Identity and Lifecycles](../core-concepts/agent-identity-and-lifecycle.md)\n",@@ -119,23 +176,23 @@"can be used to create different instances of the same agent class.\n","```\n","\n",- "To register an agent type with the \n",+ "To register our agent types with the \n","{py:class}`~autogen_core.SingleThreadedAgentRuntime`,\n","the following code can be used:"]},{"cell_type": "code",- "execution_count": 2,+ "execution_count": 13,"metadata": {},"outputs": [{"data": {"text/plain": [- "AgentType(type='my_agent')"+ "AgentType(type='my_assistant')"]},- "execution_count": 2,+ "execution_count": 13,"metadata": {},"output_type": "execute_result"}@@ -144,7 +201,8 @@"from autogen_core import SingleThreadedAgentRuntime\n","\n","runtime = SingleThreadedAgentRuntime()\n",- "await MyAgent.register(runtime, \"my_agent\", lambda: MyAgent())"+ "await MyAgent.register(runtime, \"my_agent\", lambda: MyAgent())\n",+ "await MyAssistant.register(runtime, \"my_assistant\", lambda: MyAssistant(\"my_assistant\"))"]},{@@ -159,21 +217,23 @@},{"cell_type": "code",- "execution_count": 3,+ "execution_count": 14,"metadata": {},"outputs": [{"name": "stdout","output_type": "stream","text": [- "Received message: Hello, World!\n"+ "my_agent received message: Hello, World!\n",+ "my_assistant received message: Hello, World!\n",+ "my_assistant responded: Hello! How can I assist you today?\n"]}],"source": [- "agent_id = AgentId(\"my_agent\", \"default\")\n","runtime.start() # Start processing messages in the background.\n",- "await runtime.send_message(MyMessageType(\"Hello, World!\"), agent_id)\n",+ "await runtime.send_message(MyMessageType(\"Hello, World!\"), AgentId(\"my_agent\", \"default\"))\n",+ "await runtime.send_message(MyMessageType(\"Hello, World!\"), AgentId(\"my_assistant\", \"default\"))\n","await runtime.stop() # Stop processing messages in the background."]},@@ -203,7 +263,7 @@},{"cell_type": "code",- "execution_count": 4,+ "execution_count": 15,"metadata": {},"outputs": [],"source": [@@ -228,7 +288,7 @@},{"cell_type": "code",- "execution_count": 5,+ "execution_count": 16,"metadata": {},"outputs": [],"source": [@@ -246,7 +306,7 @@},{"cell_type": "code",- "execution_count": 6,+ "execution_count": 17,"metadata": {},"outputs": [],"source": [diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/installation.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/installation.mdindex ff468a177..8b7d0dc2d 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/installation.md+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/installation.md@@ -1,5 +1,53 @@# Installation+## Create a Virtual Environment (optional)++When installing AgentChat locally, we recommend using a virtual environment for the installation. This will ensure that the dependencies for AgentChat are isolated from the rest of your system.++``````{tab-set}++`````{tab-item} venv++Create and activate:++```bash+python3 -m venv .venv+source .venv/bin/activate+```++To deactivate later, run:++```bash+deactivate+```++`````++`````{tab-item} conda++[Install Conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) if you have not already.+++Create and activate:++```bash+conda create -n autogen python=3.12+conda activate autogen+```++To deactivate later, run:++```bash+conda deactivate+```+++`````++++``````+## Install using pipInstall the `autogen-core` package using pip:@@ -12,3 +60,26 @@ pip install "autogen-core==0.4.0.dev13"```{note}Python 3.10 or later is required.```++## Install OpenAI for Model Client++To use the OpenAI and Azure OpenAI models, you need to install the following+extensions:++```bash+pip install "autogen-ext[openai]==0.4.0.dev13"+```++If you are using Azure OpenAI with AAD authentication, you need to install the following:++```bash+pip install "autogen-ext[azure]==0.4.0.dev13"+```++## Install Docker for Code Execution (Optional)++We recommend using Docker to use {py:class}`~autogen_ext.code_executors.docker.DockerCommandLineCodeExecutor` for execution of model-generated code.+To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/).++To learn more code execution, see [Command Line Code Executors](./framework/command-line-code-executors.ipynb)+and [Code Execution](./design-patterns/code-execution-groupchat.ipynb).