docs: update AssistantAgent documentation with a new figure, attention and warning notes (microsoft#5099)

* docs: update AssistantAgent documentation with attention and warning notes

* update

---------

Co-authored-by: Jack Gerrits <[email protected]>

Author: ekzhu

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: