Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve language of user guide #4577

Merged
merged 9 commits into from
Dec 10, 2024
Merged

Improve language of user guide #4577

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
56baf92
Improve language of agents section
gagb Dec 5, 2024
f1cc744
Accomodate victor's feedback
gagb Dec 6, 2024
a74670f
Templ changes
gagb Dec 9, 2024
2bfa773
Change outline
gagb Dec 9, 2024
a84f9de
Fix outline further
gagb Dec 9, 2024
c081932
Merge branch 'main' into gagb-docs
gagb Dec 9, 2024
beac3fb
Flatten the outline
gagb Dec 9, 2024
51d57bb
Merge branch 'main' into gagb-docs
ekzhu Dec 10, 2024
10a6e59
remove
ekzhu Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
"## Assistant Agent\n",
"\n",
"{py:class}`~autogen_agentchat.agents.AssistantAgent` is a built-in agent that\n",
"uses a language model with ability to use tools."
"uses a language model and has the ability to use tools."
]
},
{
Expand Down Expand Up @@ -59,8 +59,10 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"We can call the {py:meth}`~autogen_agentchat.agents.AssistantAgent.on_messages` \n",
"method to get the agent to respond to a message."
"\n",
"## Getting Responses\n",
"\n",
"We can use the {py:meth}`~autogen_agentchat.agents.AssistantAgent.on_messages` method to get the agent response to a given message.\n"
]
},
{
Expand Down Expand Up @@ -134,7 +136,7 @@
"source": [
"The User Proxy agent is ideally used for on-demand human-in-the-loop interactions for scenarios such as Just In Time approvals, human feedback, alerts, etc. For slower user interactions, consider terminating the session using a termination condition and start another one from run or run_stream with another message.\n",
"\n",
"### Stream Messages\n",
"## Streaming Messages\n",
"\n",
"We can also stream each message as it is generated by the agent by using the\n",
"{py:meth}`~autogen_agentchat.agents.AssistantAgent.on_messages_stream` method,\n",
Expand Down Expand Up @@ -172,7 +174,7 @@
"\n",
"\n",
"async def assistant_run_stream() -> None:\n",
" # Option 1: read each message from the stream.\n",
" # Option 1: read each message from the stream (as shown in the previous example).\n",
" # async for message in agent.on_messages_stream(\n",
" # [TextMessage(content=\"Find information on AutoGen\", source=\"user\")],\n",
" # cancellation_token=CancellationToken(),\n",
Expand All @@ -198,12 +200,12 @@
"source": [
"The {py:meth}`~autogen_agentchat.agents.AssistantAgent.on_messages_stream` method\n",
"returns an asynchronous generator that yields each inner message generated by the agent,\n",
"and the last item is the final response message in the {py:attr}`~autogen_agentchat.base.Response.chat_message` attribute.\n",
"with the final item being the response message in the {py:attr}`~autogen_agentchat.base.Response.chat_message` attribute.\n",
"\n",
"From the messages, you can see the assistant agent used the `web_search` tool to\n",
"search for information and responded using the search results.\n",
"From the messages, you can observe that the assistant agent utilized the `web_search` tool to\n",
"gather information and responded based on the search results.\n",
"\n",
"### Understanding Tool Calling\n",
"## Understanding Tool Calling\n",
"\n",
"Large Language Models (LLMs) are typically limited to generating text or code responses. However, many complex tasks benefit from the ability to use external tools that perform specific actions, such as fetching data from APIs or databases.\n",
"\n",
Expand Down Expand Up @@ -233,8 +235,7 @@
"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."
"Having explored the usage of the {py:class}`~autogen_agentchat.agents.AssistantAgent`, we can now proceed to the next section to learn about the teams feature in AgentChat.\n"
]
},
{
Expand Down
159 changes: 64 additions & 95 deletions python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,48 +6,22 @@
"source": [
"# Teams\n",
"\n",
"```{include} ../warning.md\n",
"```\n",
"\n",
"In AgentChat, teams define how groups of agents collaborate to address tasks.\n",
"A team is composed of one or more agents, and interacts with your application\n",
"by receiving task and returning task result.\n",
"It is stateful and maintains context across multiple tasks.\n",
"A team uses a stateful termination condition to determine when to stop processing the\n",
"current task.\n",
"\n",
"The diagram below shows the relationship between team and your application.\n",
"\n",
"![AgentChat Teams](./agentchat-team.svg)\n",
"In this section you'll learn how to create a _multi-agent team_ (or simply team) using AutoGen. A team is a group of agents that work together to achieve a common goal.\n",
"\n",
"AgentChat provides several preset teams that implements one or more [multi-agent design patterns](../../core-user-guide/design-patterns/index.md) to simplify development. Here is a list of the preset teams:\n",
"We'll first show you hot create and run a team. We'll then explain how to observe the team's behavior, which is crucial for debugging and understanding the team's performance, and common operations to control the team's behavior.\n",
"\n",
"- {py:class}`~autogen_agentchat.teams.RoundRobinGroupChat`: All participants share context and takes turn to respond in a round-robin fashion. We will cover this team in this section.\n",
"- {py:class}`~autogen_agentchat.teams.SelectorGroupChat`: All participants share context and use a model-based selector (with custom override) to select the next agent to respond. See [Selector Group Chat](./selector-group-chat.ipynb) for more details.\n",
"- {py:class}`~autogen_agentchat.teams.Swarm`: All participants share context and use {py:class}`~autogen_agentchat.messages.HandoffMessage`to pass control to the next agent. See [Swarm](./swarm.ipynb) for more details.\n",
"\n",
"At a high-level, a team API consists of the following methods:\n",
"\n",
"- {py:meth}`~autogen_agentchat.base.TaskRunner.run`: Process a task, which can be a {py:class}`str`, {py:class}`~autogen_agentchat.messages.TextMessage`, {py:class}`~autogen_agentchat.messages.MultiModalMessage`, or {py:class}`~autogen_agentchat.messages.HandoffMessage`, and returns {py:class}`~autogen_agentchat.base.TaskResult`. The task can also be `None` to resume processing the previous task if the team has not been reset.\n",
"- {py:meth}`~autogen_agentchat.base.TaskRunner.run_stream`: Similar to {py:meth}`~autogen_agentchat.base.TaskRunner.run`, but it returns an async generator of messages and the final task result.\n",
"- {py:meth}`~autogen_agentchat.base.Team.reset`: To reset the team state if the next task is not related to the previous task. Otherwise, the team can utilize the context from the previous task to process the next one.\n",
"\n",
"In this section, we will be using the\n",
"{py:class}`~autogen_agentchat.teams.RoundRobinGroupChat` team to introduce the AgentChat team API."
"We'll start by focusing on a simple team with consisting of a single agent (the baseline case) and use a round robin strategy to select the agent to act. We'll then show how to create a team with multiple agents and how to implement a more sophisticated strategy to select the agent to act."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Round-Robin Group Chat\n",
"## Creating a Team\n",
"\n",
"{py:class}`~autogen_agentchat.teams.RoundRobinGroupChat` is a simple team that allows all agents to share context and take turns to respond in a round-robin fashion.\n",
"On its turn, each agent broadcasts its response to all other agents in the team, so all agents have the same context.\n",
"{py:class}`~autogen_agentchat.teams.RoundRobinGroupChat` is a simple yet effective team configuration where all agents share the same context and take turns responding in a round-robin fashion. Each agent, during its turn, broadcasts its response to all other agents, ensuring that the entire team maintains a consistent context.\n",
"\n",
"We will start by creating a team with a single {py:class}`~autogen_agentchat.agents.AssistantAgent` agent\n",
"and {py:class}`~autogen_agentchat.conditions.TextMentionTermination`\n",
"termination condition that stops the team when a word is detected."
"We will begin by creating a team with a single {py:class}`~autogen_agentchat.agents.AssistantAgent` and a {py:class}`~autogen_agentchat.conditions.TextMentionTermination` condition that stops the team when a specific word is detected in the agent's response.\n"
]
},
{
Expand Down Expand Up @@ -93,7 +67,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Running Team\n",
"## Running a Team\n",
"\n",
"Let's calls the {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run` method\n",
"to start the team with a task."
Expand Down Expand Up @@ -136,45 +110,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Reseting Team\n",
"## Observability\n",
"\n",
"You can reset the team by calling the {py:meth}`~autogen_agentchat.teams.BaseGroupChat.reset` method.\n",
"It will clear the team's state including all of its agents'."
"Similar to the agent's {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream` method, you can stream the team's messages by calling the {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run_stream` method. This method returns a generator that yields messages produced by the agents in the team as they are generated, with the final item being the task result.\n"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [],
"source": [
"await single_agent_team.reset() # Reset the team for the next run."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It is usually a good idea to reset the team if the next task is not related to the previous task.\n",
"However, if the next task is related to the previous task, you don't need to reset.\n",
"See [Resuming Team](#resuming-team) below."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Streaming Team Messages\n",
"\n",
"Similar to agent's {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream` method,\n",
"you can stream the team's messages by calling the {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run_stream` method.\n",
"It will return a generator that yields the messages produced by the agents in the team as they are generated,\n",
"and the last item will be the task result."
]
},
{
"cell_type": "code",
"execution_count": 14,
"execution_count": null,
"metadata": {},
"outputs": [
{
Expand Down Expand Up @@ -210,10 +153,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"As the above example shows, you can obtain the reason why the team stopped by checking the {py:attr}`~autogen_agentchat.base.TaskResult.stop_reason` attribute.\n",
"As demonstrated in the example above, you can determine the reason why the team stopped by checking the {py:attr}`~autogen_agentchat.base.TaskResult.stop_reason` attribute.\n",
"\n",
"There is a covenient method {py:meth}`~autogen_agentchat.ui.Console` that prints the messages to the console\n",
"with proper formatting."
"The {py:meth}`~autogen_agentchat.ui.Console` method provides a convenient way to print messages to the console with proper formatting.\n"
]
},
{
Expand Down Expand Up @@ -258,23 +200,54 @@
") # Stream the messages to the console."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Controlling a Team\n",
"\n",
"You can reset the team by calling the {py:meth}`~autogen_agentchat.teams.BaseGroupChat.reset` method. This method will clear the team's state, including all agents."
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [],
"source": [
"await single_agent_team.reset() # Reset the team for the next run."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It is usually a good idea to reset the team if the next task is not related to the previous task.\n",
"However, if the next task is related to the previous task, you don't need to reset and you can instead resume. We will cover this in the next section."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"## Team Usage Guide\n",
"\n",
"We will now implement a slightly more complex team with multiple agents and learn how to resume the team after stopping it and even involve the user in the conversation.\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Reflection Pattern\n",
"\n",
"Now we will create a team with two agents that implements the\n",
"Reflection pattern, which is a multi-agent design pattern that uses\n",
"a critic agent to evaluate the responses of a primary agent.\n",
"We will now create a team with two agents that implement the _reflection_ pattern, a multi-agent design pattern where a critic agent evaluates the responses of a primary agent.\n",
"\n",
"See how the reflection pattern works using the [Core API](../../core-user-guide/design-patterns/reflection.ipynb).\n",
"Learn more about the reflection pattern using the [Core API](../../core-user-guide/design-patterns/reflection.ipynb).\n",
"\n",
"In this example, we will use the {py:class}`~autogen_agentchat.agents.AssistantAgent` agent class\n",
"for both the primary and critic agents.\n",
"We will use both the {py:class}`~autogen_agentchat.conditions.TextMentionTermination`\n",
"and {py:class}`~autogen_agentchat.conditions.MaxMessageTermination` termination conditions\n",
"together to stop the team."
"In this example, we will use the {py:class}`~autogen_agentchat.agents.AssistantAgent` class for both the primary and critic agents. We will combine the {py:class}`~autogen_agentchat.conditions.TextMentionTermination` and {py:class}`~autogen_agentchat.conditions.MaxMessageTermination` conditions to stop the team.\n"
]
},
{
Expand Down Expand Up @@ -418,7 +391,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Resuming Team\n",
"### Resuming a Team\n",
"\n",
"Let's run the team again with a new task while keeping the context about the previous task."
]
Expand Down Expand Up @@ -552,7 +525,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Resuming A Previous Task\n",
"### Resuming a Previous Task\n",
"\n",
"We can call {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run` or {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run_stream` methods\n",
"without setting the `task` again to resume the previous task. The team will continue from where it left off."
Expand Down Expand Up @@ -600,29 +573,25 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Pause for User Input\n",
"### Pausing for User Input\n",
"\n",
"Often times, team needs additional input from the application (i.e., user)\n",
"to continue processing the task. We will show two possible ways to do it:\n",
"Sometimes, teams may require additional input from the application (e.g., the user) to continue making meaningful progress on a task. Here are two ways to achieve this:\n",
"\n",
"- Set the maximum number of turns such that the team stops after the specified number of turns.\n",
"- Set the maximum number of turns so that the team stops after the specified number of turns.\n",
"- Use the {py:class}`~autogen_agentchat.conditions.HandoffTermination` termination condition.\n",
"\n",
"You can also use custom termination conditions, see [Termination Conditions](./termination.ipynb)."
"You can also create custom termination conditions. For more details, see [Termination Conditions](./termination.ipynb).\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Maximum Number of Turns\n",
"#### Via Max Turns\n",
"\n",
"This is the simplest way to pause the team for user input. For example,\n",
"you can set the maximum number of turns to 1 such that the team stops right\n",
"after the first agent responds. This is useful when you want the user\n",
"to constantly engage with the team, such as in a chatbot scenario.\n",
"This method allows you to pause the team for user input by setting a maximum number of turns. For instance, you can configure the team to stop after the first agent responds by setting `max_turns` to 1. This is particularly useful in scenarios where continuous user engagement is required, such as in a chatbot.\n",
"\n",
"Simply set the `max_turns` parameter in the {py:meth}`~autogen_agentchat.teams.RoundRobinGroupChat` constructor.\n",
"To implement this, set the `max_turns` parameter in the {py:meth}`~autogen_agentchat.teams.RoundRobinGroupChat` constructor.\n",
"\n",
"```python\n",
"team = RoundRobinGroupChat([...], max_turns=1)\n",
Expand All @@ -640,7 +609,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Using Handoff to Pause Team\n",
"#### Via Handoff\n",
"\n",
"You can use the {py:class}`~autogen_agentchat.conditions.HandoffTermination` termination condition\n",
"to stop the team when an agent sends a {py:class}`~autogen_agentchat.messages.HandoffMessage` message.\n",
Expand All @@ -649,7 +618,7 @@
"with a handoff setting.\n",
"\n",
"```{note}\n",
"The model used with {py:class}`~autogen_agentchat.agents.AssistantAgent`must support tool call\n",
"The model used with {py:class}`~autogen_agentchat.agents.AssistantAgent` must support tool call\n",
"to use the handoff feature.\n",
"```"
]
Expand Down Expand Up @@ -792,4 +761,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
}
}
5 changes: 0 additions & 5 deletions python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/warning.md
View file
Open in desktop

This file was deleted.

Loading