From 9b1260dd3ea8de894e301ddb7cdad77cd860a69f Mon Sep 17 00:00:00 2001 From: Eric Zhu Date: Fri, 17 Jan 2025 15:49:02 -0800 Subject: [PATCH] docs: update AssistantAgent documentation with a new figure, attention and warning notes (#5099) * docs: update AssistantAgent documentation with attention and warning notes * update --------- Co-authored-by: Jack Gerrits --- .../agents/_assistant_agent.py | 12 +- .../docs/drawio/assistant-agent.drawio | 203 ++++++++++++++++++ .../docs/src/images/assistant-agent.svg | 3 + 3 files changed, 215 insertions(+), 3 deletions(-) create mode 100644 python/packages/autogen-core/docs/drawio/assistant-agent.drawio create mode 100644 python/packages/autogen-core/docs/src/images/assistant-agent.svg diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py index 85825e47beb5..65e01817f59b 100644 --- a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py +++ b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py @@ -77,26 +77,31 @@ class AssistantAgent(BaseChatAgent, Component[AssistantAgentConfig]): the inner messages as they are created, and the :class:`~autogen_agentchat.base.Response` object as the last item before closing the generator. - .. note:: + .. attention:: The caller must only pass the new messages to the agent on each call to the :meth:`on_messages` or :meth:`on_messages_stream` method. The agent maintains its state between calls to these methods. Do not pass the entire conversation history to the agent on each call. - .. note:: + .. warning:: The assistant agent is not thread-safe or coroutine-safe. It should not be shared between multiple tasks or coroutines, and it should not call its methods concurrently. + The following diagram shows how the assistant agent works: + + .. image:: ../../images/assistant-agent.svg + Tool call behavior: * If the model returns no tool call, then the response is immediately returned as a :class:`~autogen_agentchat.messages.TextMessage` in :attr:`~autogen_agentchat.base.Response.chat_message`. * When the model returns tool calls, they will be executed right away: - When `reflect_on_tool_use` is False (default), the tool call results are returned as a :class:`~autogen_agentchat.messages.ToolCallSummaryMessage` in :attr:`~autogen_agentchat.base.Response.chat_message`. `tool_call_summary_format` can be used to customize the tool call summary. - When `reflect_on_tool_use` is True, the another model inference is made using the tool calls and results, and the text response is returned as a :class:`~autogen_agentchat.messages.TextMessage` in :attr:`~autogen_agentchat.base.Response.chat_message`. + * If the model returns multiple tool calls, they will be executed concurrently. To disable parallel tool calls you need to configure the model client. For example, set `parallel_tool_calls=False` for :class:`~autogen_ext.models.openai.OpenAIChatCompletionClient` and :class:`~autogen_ext.models.openai.AzureOpenAIChatCompletionClient`. - .. note:: + .. tip:: By default, the tool call results are returned as response when tool calls are made. So it is recommended to pay attention to the formatting of the tools return values, especially if another agent is expecting them in a specific format. @@ -111,6 +116,7 @@ class AssistantAgent(BaseChatAgent, Component[AssistantAgentConfig]): .. note:: If multiple handoffs are detected, only the first handoff is executed. + To avoid this, disable parallel tool calls in the model client configuration. Limit context size sent to the model: diff --git a/python/packages/autogen-core/docs/drawio/assistant-agent.drawio b/python/packages/autogen-core/docs/drawio/assistant-agent.drawio new file mode 100644 index 000000000000..709bb3727b20 --- /dev/null +++ b/python/packages/autogen-core/docs/drawio/assistant-agent.drawio @@ -0,0 +1,203 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/python/packages/autogen-core/docs/src/images/assistant-agent.svg b/python/packages/autogen-core/docs/src/images/assistant-agent.svg new file mode 100644 index 000000000000..fc1ce4ba1b38 --- /dev/null +++ b/python/packages/autogen-core/docs/src/images/assistant-agent.svg @@ -0,0 +1,3 @@ + + +
Model Context
Model Context
Model Context
Model Context
New Messages
New Messages
Memory
Memory
Model Client
Model Client
Tools
Tools
Model Context
Model Context
1. Add New Messages to Context
1. Add New Messages to Context
Model Context
Model Context
2. Update Context
2. Update Context
Model Context
Model Context
3. Chat Completion
3. Chat Completion
Model Context
Model Context
Model Context
Model Context
Model Context
Model Context
4. Tool Execution
4. Tool Execution
Model Client
Model Client
5. Chat Completion (Reflect on Tool Use)
5. Chat Completion (R...
Model Context
Model Context
Model Context
Model Context
Model Context
Model Context
Model Context
Model Context
Response
(Text)
Response...
Response 
(Tool Result Summary)
Response...
Response 
(Text Message)
Response...
Model Context
Model Context
Model Context
Model Context
Model Context
Model Context
Tool Call Detected?
Tool Call Detected?
Reflect on Tool Use?
Reflect on Tool Use?
No
No
No
No
Handoff Detected?
Handoff Detected?
Response
(Handoff)
Response...
Yes
Yes
Assistant Agent
Assistant Agent \ No newline at end of file