From ac363344dab9783b5feee0a9fdd8fae9bf9f60f9 Mon Sep 17 00:00:00 2001 From: gagb Date: Thu, 5 Dec 2024 14:37:33 -0800 Subject: [PATCH] Update user guide (#4560) * Update user guide * Fix typos * Move the file to correct dir * update notebook, add runnable code to catch bugs, improve text on inner messages * update icons in tutorial * Reduce references to future concepts --------- Co-authored-by: Victor Dibia --- .../tutorial/agents.ipynb | 3 - .../agentchat-user-guide/tutorial/index.md | 9 +- .../tutorial/messages.ipynb | 127 ++++++++++++++++++ 3 files changed, 135 insertions(+), 4 deletions(-) create mode 100644 python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/messages.ipynb 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.ipynb index 7f9d789ac..dcb82f139 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 @@ -6,9 +6,6 @@ "source": [ "# Agents\n", "\n", - "```{include} ../warning.md\n", - "```\n", - "\n", "AutoGen AgentChat provides a set of preset Agents, each with variations in how an agent might respond to messages.\n", "All agents share the following attributes and methods:\n", "\n", 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.md index 4ffadc2a9..a7c97d9de 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 @@ -18,6 +18,12 @@ Get started with AgentChat through this comprehensive tutorial. Setting up model clients for agents and teams. ::: +:::{grid-item-card} {fas}`message;pst-color-primary` Messages +:link: ./messages.html + +Understanding different types of messages. +::: + :::{grid-item-card} {fas}`users;pst-color-primary` Agents :link: ./agents.html @@ -48,7 +54,7 @@ A dynamic team that uses handoffs to pass tasks between agents. How to build custom agents. ::: -:::{grid-item-card} {fas}`users;pst-color-primary` State Management +:::{grid-item-card} {fas}`database;pst-color-primary` State Management :link: ./state.html How to manage state in agents and teams. @@ -61,6 +67,7 @@ How to manage state in agents and teams. :hidden: models +messages agents teams selector-group-chat diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/messages.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/messages.ipynb new file mode 100644 index 000000000..f677c02e5 --- /dev/null +++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/messages.ipynb @@ -0,0 +1,127 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Messages" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In AutoGen, _messages_ facilitate communication and information exchange with other agents, orchestrators, and applications. AgentChat supports various message types, each designed for specific purposes." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Types of Messages\n", + "\n", + "At a high level, messages in AgentChat can be categorized into two types: agent-agent messages and an agent's internal events and messages.\n", + "\n", + "### Agent-Agent Messages\n", + "AgentChat supports many message types for agent-to-agent communication. The most common one is the {py:class}`~autogen_agentchat.messages.ChatMessage`. This message type allows both text and multimodal communication and subsumes other message types, such as {py:class}`~autogen_agentchat.messages.TextMessage` or {py:class}`~autogen_agentchat.messages.MultiModalMessage`.\n", + "\n", + "For example, the following code snippet demonstrates how to create a text message, which accepts a string content and a string source:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from autogen_agentchat.messages import TextMessage\n", + "\n", + "text_message = TextMessage(content=\"Hello, world!\", source=\"User\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Similarly, the following code snippet demonstrates how to create a multimodal message, which accepts\n", + "a list of strings or {py:class}`~autogen_core.Image` objects:" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from autogen_agentchat.messages import MultiModalMessage\n", + "from autogen_core import Image as AGImage\n", + "from PIL import Image\n", + "from io import BytesIO\n", + "import requests\n", + "\n", + "pil_image = Image.open(BytesIO(requests.get(\"https://picsum.photos/300/200\").content))\n", + "img = AGImage(pil_image)\n", + "multi_modal_message = MultiModalMessage(content=[\"Can you describe the content of this image?\", img], source=\"User\")\n", + "img" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The {py:class}`~autogen_agentchat.messages.TextMessage` and {py:class}`~autogen_agentchat.messages.MultiModalMessage` we have created can be passed to agents directly via the `agent.on_messages` method, or as tasks given to a team {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run` method. Messages are also used in the responses of an agent. We will explain these in more detail in the next sections." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Internal Events and Messages\n", + "\n", + "AgentChat also supports the concept of `inner_messages` - messages that are internal to an agent. These messages are used to communicate events and information on actions _within_ the agent itself.\n", + "\n", + "Examples of these include {py:class}`~autogen_agentchat.messages.ToolCallMessage`, which indicates that a request was made to call a tool, and {py:class}`~autogen_agentchat.messages.ToolCallResultMessage`, which contains the results of tool calls.\n", + "\n", + "Typically, these messages are created by the agent itself and are usually contained in the `inner_messages` field of its response. If you are building a custom agent and have events that you want to communicate to other entities (e.g., a UI), you can append these to the `inner_messages` field of the response. We will show examples of this in the next sections.\n", + "\n", + "\n", + "You can read about the full set of messages supported in AgentChat in the {py:mod}`~autogen_agentchat.messages` module. Note that this is not an exhaustive list, and you can create custom messages as needed by subclassing the {py:class}`~autogen_agentchat.messages.BaseMessage` class." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "agnext", + "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.9" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}