github/autogen
1
1
Fork 0
mirror of https://github.com/microsoft/autogen.git synced 2026-02-11 06:45:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improves tutorial (#4507)

Browse Source 
* Change nav depth

* Remove repetitive module names

* Increase nav depth

* Decrease base font size of docs

* Improve docs

* Undo css change
This commit is contained in:
gagb
2024-12-03 16:54:53 -08:00
committed by GitHub
parent 31cb50bce9
commit 6706dce577
5 changed files with 188 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -13,18 +13,9 @@ 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
AgentChat provides 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
```
```{tip}
If you are interested in implementing complex agent interaction behaviours, defining custom messaging protocols, or orchestration mechanisms, consider using the [ `autogen-core`](../core-user-guide/index.md) package.
```
::::{grid} 2 2 2 2
:gutter: 3

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

@@ -7,7 +7,7 @@ myst:
# Installation
## Create a virtual environment (optional)
## Create a Virtual Environment (optional)
When installing AgentChat locally, we recommend using a virtual environment for the installation. This will ensure that the dependencies for AgentChat are isolated from the rest of your system.
@@ -55,7 +55,7 @@ conda deactivate
``````
## Intall the AgentChat package using pip
## Install Using pip
Install the `autogen-agentchat` package using pip:

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

@@ -11,15 +11,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"```{include} warning.md\n",
"\n",
"```\n",
"\n",
":::{note}\n",
"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",
"Via 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",

6
python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/index.md
View File

@@ -7,11 +7,7 @@ myst:
# Tutorial
Tutorial to get started with AgentChat.
```{include} ../warning.md
```
Get started with AgentChat through this comprehensive tutorial.
::::{grid} 2 2 2 3
:gutter: 3

368
python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynb
View File

@@ -1,187 +1,185 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Models\n",
"\n",
"In many cases, agents need access to model services such as OpenAI, Azure OpenAI, and local models.\n",
"AgentChat utilizes model clients provided by the\n",
"[`autogen-ext`](../../core-user-guide/framework/model-clients.ipynb) package."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## OpenAI\n",
"\n",
"To access OpenAI models, you need to install the `openai` extension to use the {py:class}`~autogen_ext.models.OpenAIChatCompletionClient`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"pip install 'autogen-ext[openai]==0.4.0.dev8'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You will also need to obtain an [API key](https://platform.openai.com/account/api-keys) from OpenAI."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"from autogen_ext.models import OpenAIChatCompletionClient\n",
"\n",
"opneai_model_client = OpenAIChatCompletionClient(\n",
" model=\"gpt-4o-2024-08-06\",\n",
" # api_key=\"sk-...\", # Optional if you have an OPENAI_API_KEY environment variable set.\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To test the model client, you can use the following code:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"CreateResult(finish_reason='stop', content='The capital of France is Paris.', usage=RequestUsage(prompt_tokens=15, completion_tokens=7), cached=False, logprobs=None)\n"
]
}
],
"source": [
"from autogen_core.components.models import UserMessage\n",
"\n",
"result = await opneai_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
"print(result)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```{note}\n",
"You can use this client with models hosted on OpenAI-compatible endpoints, however, we have not tested this functionality.\n",
"See {py:class}`~autogen_ext.models.OpenAIChatCompletionClient` for more information.\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Azure OpenAI\n",
"\n",
"Install the `azure` and `openai` extensions to use the {py:class}`~autogen_ext.models.AzureOpenAIChatCompletionClient`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"pip install 'autogen-ext[openai,azure]==0.4.0.dev8'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To use the client, you need to provide your deployment id, Azure Cognitive Services endpoint, api version, and model capabilities.\n",
"For authentication, you can either provide an API key or an Azure Active Directory (AAD) token credential.\n",
"\n",
"The following code snippet shows how to use AAD authentication.\n",
"The identity used must be assigned the [Cognitive Services OpenAI User](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control#cognitive-services-openai-user) role."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from autogen_ext.models import AzureOpenAIChatCompletionClient\n",
"from azure.identity import DefaultAzureCredential, get_bearer_token_provider\n",
"\n",
"# Create the token provider\n",
"token_provider = get_bearer_token_provider(DefaultAzureCredential(), \"https://cognitiveservices.azure.com/.default\")\n",
"\n",
"az_model_client = AzureOpenAIChatCompletionClient(\n",
" azure_deployment=\"{your-azure-deployment}\",\n",
" model=\"{model-name, such as gpt-4o}\",\n",
" api_version=\"2024-06-01\",\n",
" azure_endpoint=\"https://{your-custom-endpoint}.openai.azure.com/\",\n",
" azure_ad_token_provider=token_provider, # Optional if you choose key-based authentication.\n",
" # api_key=\"sk-...\", # For key-based authentication.\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"See [here](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity#chat-completions) for how to use the Azure client directly or for more info."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Local Models\n",
"\n",
"We are working on it. Stay tuned!"
]
}
],
"metadata": {
"kernelspec": {
"display_name": ".venv",
"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.5"
}
},
"nbformat": 4,
"nbformat_minor": 2
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Models\n",
"\n",
"In many cases, agents need access to LLM model services such as OpenAI, Azure OpenAI, or local models. Since there are many different providers with different APIs, `autogen-core` implements a protocol for [model clients](../../core-user-guide/framework/model-clients.ipynb) and `autogen-ext` implements a set of model clients for popular model services. AgentChat can use these model clients to interact with model services. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## OpenAI\n",
"\n",
"To access OpenAI models, install the `openai` extension, which allows you to use the {py:class}`~autogen_ext.models.OpenAIChatCompletionClient`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"pip install 'autogen-ext[openai]==0.4.0.dev8'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You will also need to obtain an [API key](https://platform.openai.com/account/api-keys) from OpenAI."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"from autogen_ext.models import OpenAIChatCompletionClient\n",
"\n",
"opneai_model_client = OpenAIChatCompletionClient(\n",
" model=\"gpt-4o-2024-08-06\",\n",
" # api_key=\"sk-...\", # Optional if you have an OPENAI_API_KEY environment variable set.\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To test the model client, you can use the following code:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"CreateResult(finish_reason='stop', content='The capital of France is Paris.', usage=RequestUsage(prompt_tokens=15, completion_tokens=7), cached=False, logprobs=None)\n"
]
}
],
"source": [
"from autogen_core.components.models import UserMessage\n",
"\n",
"result = await opneai_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
"print(result)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```{note}\n",
"You can use this client with models hosted on OpenAI-compatible endpoints, however, we have not tested this functionality.\n",
"See {py:class}`~autogen_ext.models.OpenAIChatCompletionClient` for more information.\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Azure OpenAI\n",
"\n",
"Similarly, install the `azure` and `openai` extensions to use the {py:class}`~autogen_ext.models.AzureOpenAIChatCompletionClient`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"pip install 'autogen-ext[openai,azure]==0.4.0.dev8'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To use the client, you need to provide your deployment id, Azure Cognitive Services endpoint, api version, and model capabilities.\n",
"For authentication, you can either provide an API key or an Azure Active Directory (AAD) token credential.\n",
"\n",
"The following code snippet shows how to use AAD authentication.\n",
"The identity used must be assigned the [Cognitive Services OpenAI User](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control#cognitive-services-openai-user) role."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from autogen_ext.models import AzureOpenAIChatCompletionClient\n",
"from azure.identity import DefaultAzureCredential, get_bearer_token_provider\n",
"\n",
"# Create the token provider\n",
"token_provider = get_bearer_token_provider(DefaultAzureCredential(), \"https://cognitiveservices.azure.com/.default\")\n",
"\n",
"az_model_client = AzureOpenAIChatCompletionClient(\n",
" azure_deployment=\"{your-azure-deployment}\",\n",
" model=\"{model-name, such as gpt-4o}\",\n",
" api_version=\"2024-06-01\",\n",
" azure_endpoint=\"https://{your-custom-endpoint}.openai.azure.com/\",\n",
" azure_ad_token_provider=token_provider, # Optional if you choose key-based authentication.\n",
" # api_key=\"sk-...\", # For key-based authentication.\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"See [here](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity#chat-completions) for how to use the Azure client directly or for more information."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Local Models\n",
"\n",
"We are working on it. Stay tuned!"
]
}
],
"metadata": {
"kernelspec": {
"display_name": ".venv",
"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.5"
}
},
"nbformat": 4,
"nbformat_minor": 2
}