Merge pull request #275830 from thegovind/main

add autogen tutorial for sessions

Author: v-dirichards

articles/container-apps/TOC.yml

@@ -134,6 +134,8 @@
       items:
         - name: Code interpreter sessions
           items:
+          - name: AutoGen
+            href: sessions-tutorial-autogen.md
           - name: LangChain
             href: sessions-tutorial-langchain.md
           - name: LlamaIndex

articles/container-apps/sessions-code-interpreter.md

@@ -45,7 +45,7 @@ To create a code interpreter session pool using the Azure CLI, ensure you have t
 az upgrade
 
 # Install or upgrade the Azure Container Apps extension
-az extension add --name containerapp --upgrade --allow-preview -y
+az extension add --name containerapp --upgrade --allow-preview true -y
 ```
 
 Use the `az containerapps sessionpool create` command to create the pool. The following example creates a Python code interpreter session pool named `my-session-pool`. Make sure to replace `<RESOURCE_GROUP>` with your resource group name before you run the command.

articles/container-apps/sessions-custom-container.md

@@ -42,7 +42,7 @@ To create a custom container session pool using the Azure CLI, ensure you have t
 
 ```bash
 az upgrade
-az extension add --name containerapp --upgrade --allow-preview -y
+az extension add --name containerapp --upgrade --allow-preview true -y
 ```
 
 Custom container session pools require a workload profile enabled Azure Container Apps environment. If you don't have an environment, use the `az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles` command to create one.

articles/container-apps/sessions-tutorial-autogen.md

@@ -0,0 +1,73 @@
+---
+title: "Tutorial: Use code interpreter sessions in AutoGen with Azure Container Apps"
+description: Learn to use code interpreter sessions in AutoGen on Azure Container Apps.
+services: container-apps
+author: thegovind
+ms.service: container-apps
+ms.topic: tutorial
+ms.date: 05/15/2024
+ms.author: gok
+---
+
+# Tutorial: Use code interpreter sessions in AutoGen with Azure Container Apps
+
+[AutoGen](https://microsoft.github.io/autogen/) is a framework for developing large language model (LLM) applications using multiple agents that converse with each other to solve tasks. Agents built with AutoGen can operate in various modes that employ combinations of LLMs, human inputs, and tools. One important type of tool for AutoGen agents is code executors. They enable agents to perform complex tasks by writing and executing code. By integrating Azure Container Apps dynamic sessions with AutoGen, you give the agent a [code interpreter](sessions-code-interpreter.md) to use to perform useful computations and take actions.
+
+In this tutorial, you learn how to run an AI agent authored in AutoGen in a web API. The API accepts user input and returns a response generated by the AI agent. The agent uses a code interpreter in dynamic sessions to perform calculations.
+
+> [!NOTE]
+> Azure Container Apps dynamic sessions is currently in preview. See [preview limitations](./sessions.md#preview-limitations) for more information.
+
+[!INCLUDE [sessions-tutorial-prerequisites](../../includes/container-apps/sessions-tutorial-prerequisites.md)]
+
+## Run the sample app locally
+
+Before you deploy the app to Azure Container Apps, you can run it locally to test it.
+
+### Clone the app
+
+1. Clone the [Azure Container Apps sessions samples repository](https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples).
+
+    ```bash
+    git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
+    ```
+
+1. Change to the directory that contains the sample app:
+
+    ```bash
+    cd container-apps-dynamic-sessions-samples/autogen-python-webapi
+    ```
+
+[!INCLUDE [container-apps/sessions-tutorial-configure-local](../../includes/container-apps/sessions-tutorial-configure-local-autogen.md)]
+
+### Run the app
+
+Before running the sample app, open [*main.py*](https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples/blob/main/autogen-python-webapi/main.py) in an editor and review the code. The app uses FastAPI to create a web API that accepts a user message in the query string.
+
+The following lines of code instantiate a *ACASessionsExecutor* and provides it to the autogen agent:
+
+```python
+aca_sessions_executor = ACASessionsExecutor(aca_pool_management_endpoint)
+code_executor_agent = ConversableAgent(
+    name="CodeExecutor",
+    llm_config=False,
+    code_execution_config={"executor": aca_sessions_executor},
+    human_input_mode="NEVER",
+    is_termination_msg=lambda msg: "TERMINATE" in msg.get("content", "").strip().upper()
+)
+```
+
+When it needs to perform calculations and tasks, the agent uses the code interpreter in *ACASessionsExecutor* to run the code. The code is executed in a session in the session pool. By default, a random session identifier is generated when you instantiate the tool. If the agent uses the same tool to run multiple Python code snippets, it uses the same session. To ensure each end user has a unique session, use a separate agent and tool for each user.
+
+*ACASessionsExecutor* is implemented in [*aca_sessions_executor.py*](https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples/blob/main/autogen-python-webapi/aca_sessions_executor.py).
+
+[!INCLUDE [container-apps/sessions-tutorial-run-local](../../includes/container-apps/sessions-tutorial-run-local.md)]
+
+[!INCLUDE [container-apps/sessions-tutorial-deploy-autogen](../../includes/container-apps/sessions-tutorial-deploy-autogen.md)]
+
+[!INCLUDE [container-apps/sessions-tutorial-clean-up](../../includes/container-apps/sessions-tutorial-clean-up.md)]
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Code interpreter sessions](./sessions-code-interpreter.md)

includes/container-apps/sessions-tutorial-configure-local-autogen.md

@@ -0,0 +1,93 @@
+---
+author: anthonychu
+ms.service: container-apps
+ms.topic:  include
+ms.date: 05/08/2024
+ms.author: antchu
+---
+
+### Configure the app
+
+1. Create a Python virtual environment and activate it:
+
+    ```bash
+    python3.11 -m venv .venv
+    source .venv/bin/activate
+    ```
+
+    Change the Python version in the command if you're using a different version. It's recommended to use Python 3.10 or later.
+
+    > [!NOTE]
+    > If you're using Windows, replace `.venv/bin/activate` with `.venv\Scripts\activate`.
+
+1. Install the required Python packages:
+
+    ```bash
+    python -m pip install -r requirements.txt
+    ```
+
+1. To run the app, you need to configure environment variables.
+
+    1. Retrieve the Azure OpenAI account endpoint:
+
+        ```bash
+        az cognitiveservices account show \
+            --name $AZURE_OPENAI_NAME \
+            --resource-group $RESOURCE_GROUP_NAME \
+            --query properties.endpoint \
+            --output tsv
+        ```
+
+    1. Retrieve the Azure OpenAI API key:
+
+        ```bash
+        az cognitiveservices account keys list \
+            --name $AZURE_OPENAI_NAME \
+            --resource-group $RESOURCE_GROUP_NAME \
+            --query key1 \
+            --output tsv
+        ```
+
+    1. Retrieve the Azure Container Apps session pool management endpoint:
+
+        ```bash
+        az containerapp sessionpool show \
+            --name $SESSION_POOL_NAME \
+            --resource-group $RESOURCE_GROUP_NAME \
+            --query properties.poolManagementEndpoint \
+            --output tsv
+        ```
+
+    1. Create a `.env` file in the root of the sample app directory (same location as `main.py`). Add the following content to the file:
+
+        ```text
+        OAI_CONFIG_LIST=[{"model": "gpt-4", "api_key": "<AZURE_OPENAI_KEY>", "api_type": "azure", "base_url": "<AZURE_OPENAI_ENDPOINT>", "api_version": "2023-12-01-preview"}]
+        POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
+        ```
+
+        Replace `<AZURE_OPENAI_ENDPOINT>` with the Azure OpenAI account endpoint, `<AZURE_OPENAI_KEY>` with the Azure OpenAI API key, and `<SESSION_POOL_MANAGEMENT_ENDPOINT>` with the session pool management endpoint.
+
+1. The app uses `DefaultAzureCredential` to authenticate with Azure services. On your local machine, it uses your current Azure CLI login credentials. You must give yourself the *Azure ContainerApps Session Executor* role on the session pool for the app to access the session pool.
+
+    1. Retrieve your Azure CLI user name:
+
+        ```bash
+        az account show --query user.name --output tsv
+        ```
+
+    1. Run the following commands to retrieve the session pool resource ID:
+
+        ```bash
+        az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
+        ```
+
+    1. Assign the *Azure ContainerApps Session Executor* role to your Azure CLI user on the session pool:
+
+        ```bash
+        az role assignment create \
+            --role "Azure ContainerApps Session Executor" \
+            --assignee <CLI_USERNAME> \
+            --scope <SESSION_POOL_RESOURCE_ID>
+        ```
+
+        Replace `<CLI_USERNAME>` with your Azure CLI user name and `<SESSION_POOL_RESOURCE_ID>` with the session pool resource ID.

includes/container-apps/sessions-tutorial-configure-local.md

@@ -48,7 +48,7 @@ ms.author: antchu
             --output tsv
         ```
 
-    1. Create a `.env` file in the root of the sample app directory (`langchain-python-webapi`). Add the following content to the file:
+    1. Create a `.env` file in the root of the sample app directory (same location as `main.py`). Add the following content to the file:
 
         ```text
         AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>

includes/container-apps/sessions-tutorial-deploy-autogen.md

@@ -0,0 +1,93 @@
+---
+author: anthonychu
+ms.service: container-apps
+ms.topic:  include
+ms.date: 05/08/2024
+ms.author: antchu
+---
+
+## Optional: Deploy the sample app to Azure Container Apps
+
+To deploy the FastAPI app to Azure Container Apps, you need to create a container image and push it to a container registry. Then you can deploy the image to Azure Container Apps. The `az containerapp up` command combines these steps into a single command.
+
+You then need to configure managed identity for the app and assign it the proper roles to access Azure OpenAI and the session pool.
+
+1. Set the variables for the Container Apps environment and app name:
+
+    ```bash
+    ENVIRONMENT_NAME=aca-sessions-tutorial-env
+    CONTAINER_APP_NAME=chat-api
+    ```
+
+1. Build and deploy the app to Azure Container Apps:
+
+    ```bash
+    az containerapp up \
+        --name $CONTAINER_APP_NAME \
+        --resource-group $RESOURCE_GROUP_NAME \
+        --location $SESSION_POOL_LOCATION \
+        --environment $ENVIRONMENT_NAME \
+        --env-vars 'OAI_CONFIG_LIST=[{"model": "gpt-4", "api_key": "<AZURE_OPENAI_KEY>", "api_type": "azure", "base_url": "<AZURE_OPENAI_ENDPOINT>", "api_version": "2023-12-01-preview"}]' 'POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>' \
+        --source .
+    ```
+
+    Replace `<AZURE_OPENAI_ENDPOINT>` with the Azure OpenAI account endpoint, `<AZURE_OPENAI_KEY>` with the Azure OpenAI key, and `<SESSION_POOL_MANAGMENT_ENDPOINT>` with the session pool management endpoint.
+
+1. Enable the system-assigned managed identity for the app:
+
+    ```bash
+    az containerapp identity assign \
+        --name $CONTAINER_APP_NAME \
+        --resource-group $RESOURCE_GROUP_NAME \
+        --system-assigned
+    ```
+
+1. For the app to access the session pool, you need to assign the managed identity the proper roles.
+
+    1. Retrieve the managed identity's principal ID:
+
+        ```bash
+        az containerapp show \
+            --name $CONTAINER_APP_NAME \
+            --resource-group $RESOURCE_GROUP_NAME \
+            --query identity.principalId \
+            --output tsv
+        ```
+
+    1. Retrieve the session pool resource ID:
+
+        ```bash
+        az containerapp sessionpool show \
+            --name $SESSION_POOL_NAME \
+            --resource-group $RESOURCE_GROUP_NAME \
+            --query id \
+            --output tsv
+        ```
+
+    1. Assign the managed identity the `Azure ContainerApps Session Executor` and `Contributor` roles on the session pool:
+
+        Before you run the following command, replace `<PRINCIPAL_ID>` and `<SESSION_POOL_RESOURCE_ID>` with the values you retrieved in the previous steps.
+
+        ```bash
+        az role assignment create \
+            --role "Azure ContainerApps Session Executor" \
+            --assignee <PRINCIPAL_ID> \
+            --scope <SESSION_POOL_RESOURCE_ID>
+
+        az role assignment create \
+            --role "Contributor" \
+            --assignee <PRINCIPAL_ID> \
+            --scope <SESSION_POOL_RESOURCE_ID>
+        ```
+
+1. Retrieve the app's fully qualified domain name (FQDN):
+
+    ```bash
+    az containerapp show \
+        --name $CONTAINER_APP_NAME \
+        --resource-group $RESOURCE_GROUP_NAME \
+        --query properties.configuration.ingress.fqdn \
+        --output tsv
+    ```
+
+1. Open the browser to `https://<FQDN>/docs` to test the deployed app.

includes/container-apps/sessions-tutorial-prerequisites.md

@@ -29,7 +29,7 @@ The sample app in this quickstart uses an LLM from Azure OpenAI. It also uses Az
     ```bash
     az extension remove --name containerapp
     az extension add \
-        --source https://acacli.blob.core.windows.net/sessionspreview/containerapp-0.3.50-py2.py3-none-any.whl \
+        --name containerapp \
         --allow-preview true -y
     ```