Update agentchat tutorial, refactor content (microsoft#4118)

Resolves Tutorial Chapter for Custom ChatAgent microsoft#4114 -- updated tutorial chapter on agents and custom agents
Update README example to use tool call
Added "Models" section in AgentChat tutorial.
Added place holder for Tutorial Chapter for Swarm microsoft#4113.

README.md

@@ -101,32 +101,45 @@ We look forward to your contributions!
 First install the packages:
 
 ```bash
-pip install 'autogen-agentchat==0.4.0.dev4' 'autogen-ext[docker]==0.4.0.dev4'
+pip install 'autogen-agentchat==0.4.0.dev4' 'autogen-ext[openai]==0.4.0.dev4'
 ```
 
-The following code uses code execution, you need to have [Docker installed](https://docs.docker.com/engine/install/)
-and running on your machine.
+The following code uses OpenAI's GPT-4o model and you need to provide your
+API key to run.
+To use Azure OpenAI models, follow the instruction
+[here](https://microsoft.github.io/autogen/dev/user-guide/core-user-guide/cookbook/azure-openai-with-aad-auth.html).
 
 ```python
 import asyncio
-from autogen_ext.code_executors import DockerCommandLineCodeExecutor
-from autogen_ext.models import OpenAIChatCompletionClient
-from autogen_agentchat.agents import CodeExecutorAgent, CodingAssistantAgent
+from autogen_agentchat.agents import AssistantAgent
+from autogen_agentchat.task import Console, TextMentionTermination
 from autogen_agentchat.teams import RoundRobinGroupChat
-from autogen_agentchat.task import TextMentionTermination, Console
+from autogen_ext.models import OpenAIChatCompletionClient
+
+# Define a tool
+async def get_weather(city: str) -> str:
+    return f"The weather in {city} is 73 degrees and Sunny."
 
 async def main() -> None:
-    async with DockerCommandLineCodeExecutor(work_dir="coding") as code_executor:
-        code_executor_agent = CodeExecutorAgent("code_executor", code_executor=code_executor)
-        coding_assistant_agent = CodingAssistantAgent(
-            "coding_assistant", model_client=OpenAIChatCompletionClient(model="gpt-4o", api_key="YOUR_API_KEY")
-        )
-        termination = TextMentionTermination("TERMINATE")
-        group_chat = RoundRobinGroupChat([coding_assistant_agent, code_executor_agent], termination_condition=termination)
-        stream = group_chat.run_stream(
-            task="Create a plot of NVDIA and TSLA stock returns YTD from 2024-01-01 and save it to 'nvidia_tesla_2024_ytd.png'."
-        )
-        await Console(stream)
+    # Define an agent
+    weather_agent = AssistantAgent(
+        name="weather_agent",
+        model_client=OpenAIChatCompletionClient(
+            model="gpt-4o-2024-08-06",
+            # api_key="YOUR_API_KEY",
+        ),
+        tools=[get_weather],
+    )
+
+    # Define termination condition
+    termination = TextMentionTermination("TERMINATE")
+
+    # Define a team
+    agent_team = RoundRobinGroupChat([weather_agent], termination_condition=termination)
+
+    # Run the team and stream messages to the console
+    stream = agent_team.run_stream(task="What is the weather in New York?")
+    await Console(stream)
 
 asyncio.run(main())
 ```

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md

@@ -2,14 +2,20 @@
 myst:
   html_meta:
     "description lang=en": |
-      User Guide for AgentChat, a high-level api for AutoGen
+      User Guide for AgentChat, a high-level API for AutoGen
 ---
 
 # AgentChat
 
-AgentChat is a high-level package for building multi-agent applications built on top of the [ `autogen-core`](../core-user-guide/index.md) package. For beginner users, AgentChat is the recommended starting point. For advanced users, [ `autogen-core`](../core-user-guide/index.md) provides more flexibility and control over the underlying components.
+AgentChat is a high-level API for building multi-agent applications.
+It is built on top of the [`autogen-core`](../core-user-guide/index.md) package.
+For beginner users, AgentChat is the recommended starting point.
+For advanced users, [`autogen-core`](../core-user-guide/index.md)'s event-driven
+programming model provides more flexibility and control over the underlying components.
 
-AgentChat aims to provide intuitive defaults, such as **Agents** with preset behaviors and **Teams** with predefined communication protocols, to simplify building multi-agent applications.
+AgentChat aims to provide intuitive defaults, such as **Agents** with preset
+behaviors and **Teams** with predefined [multi-agent design patterns](../core-user-guide/design-patterns/index.md).
+to simplify building multi-agent applications.
 
 ```{include} warning.md
 

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/installation.md

@@ -64,6 +64,15 @@ Install the `autogen-agentchat` package using pip:
 pip install 'autogen-agentchat==0.4.0.dev4'
 ```
 
+## 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.dev4'
+```
+
 ## Install Docker for Code Execution
 
 We recommend using Docker for code execution.

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/quickstart.ipynb

@@ -19,11 +19,33 @@
     "For installation instructions, please refer to the [installation guide](./installation).\n",
     ":::\n",
     "\n",
+    "In AutoGen AgentChat, you can build applications quickly using preset agents.\n",
+    "To illustrate this, we will begin with creating a team of a single agent\n",
+    "that can use tools and respond to messages.\n",
     "\n",
-    "\n",
-    "An agent is a software entity that communicates via messages, maintains its own state, and performs actions in response to received messages or changes in its state. \n",
-    "\n",
-    "In AgentChat, agents can be rapidly implemented using preset agent configurations. To illustrate this, we will begin with creating an agent that can address tasks by responding to messages it receives. "
+    "The following code uses the OpenAI model. If you haven't already, you need to\n",
+    "install the following package and extension:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pip install 'autogen-agentchat==0.4.0.dev4' 'autogen-ext[openai]==0.4.0.dev4'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To use Azure OpenAI models and AAD authentication,\n",
+    "you can follow the instructions [here](./tutorial/models.ipynb#azure-openai)."
    ]
   },
   {
@@ -73,7 +95,10 @@
     "    # Define an agent\n",
     "    weather_agent = AssistantAgent(\n",
     "        name=\"weather_agent\",\n",
-    "        model_client=OpenAIChatCompletionClient(model=\"gpt-4o-2024-08-06\"),\n",
+    "        model_client=OpenAIChatCompletionClient(\n",
+    "            model=\"gpt-4o-2024-08-06\",\n",
+    "            # api_key=\"YOUR_API_KEY\",\n",
+    "        ),\n",
     "        tools=[get_weather],\n",
     "    )\n",
     "\n",
@@ -83,7 +108,7 @@
     "    # Define a team\n",
     "    agent_team = RoundRobinGroupChat([weather_agent], termination_condition=termination)\n",
     "\n",
-    "    # Run the team and stream messages\n",
+    "    # Run the team and stream messages to the console\n",
     "    stream = agent_team.run_stream(task=\"What is the weather in New York?\")\n",
     "    await Console(stream)\n",
     "\n",
@@ -96,7 +121,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The code snippet above introduces two high level concepts in AgentChat: `Agent` and `Team`.  An Agent helps us define what actions are taken when a message is received. Specifically, we use the `AssistantAgent` preset - an agent that can be given tools (functions) that it can then use to address tasks.  A Team helps us define the rules for how agents interact with each other.  In the  `RoundRobinGroupChat` team, agents receive messages in a sequential round-robin fashion.  "
+    "The code snippet above introduces two high level concepts in AgentChat: *Agent* and *Team*.  An Agent helps us define what actions are taken when a message is received. Specifically, we use the {py:class}`~autogen_agentchat.agents.AssistantAgent` preset - an agent that can be given access to a model (e.g., LLM) and tools (functions) that it can then use to address tasks.  A Team helps us define the rules for how agents interact with each other.  In the  {py:class}`~autogen_agentchat.teams.RoundRobinGroupChat` team, agents respond in a sequential round-robin fashion.\n",
+    "In this case, we have a single agent, so the same agent is used for each round."
    ]
   },
   {