diff --git a/samples/csharp/hosted-agents/AGENTS.md b/samples/csharp/hosted-agents/AGENTS.md new file mode 100644 index 000000000..85dbb9492 --- /dev/null +++ b/samples/csharp/hosted-agents/AGENTS.md @@ -0,0 +1,51 @@ +# Coding Agent Instructions — C# hosted-agent samples + +Conventions for AI agents creating or editing samples under +`samples/csharp/hosted-agents/`. Agents read the nearest `AGENTS.md` up the +tree, so this applies to C# hosted-agent samples. Treat these as shared +conventions and a starting point — adapt to what each sample actually needs. + +## README conventions + +Most samples follow the shared template, +[`README-template.md`](./README-template.md): a good default is to copy it and +fill in the `{{placeholders}}`. It keeps a familiar section flow: + +1. What this sample demonstrates +2. How it works — plus any sample-specific background (e.g. "Environment + variables", "Architecture", "Features") +3. Prerequisites — what the *sample* needs: a Foundry project + model deployment, + the **.NET 10 SDK**, and (only if applicable) RBAC roles, extra Azure + resources, and environment variables / secrets +4. Option 1: Azure Developer CLI (`azd`) — init → provision → run → invoke → + deploy → invoke-deployed +5. Option 2: VS Code (Foundry Toolkit) — the one-click **F5** run-and-debug flow + (Agent Inspector opens automatically) and/or a manual run (`dotnet restore` → + configure env → `az login` → `dotnet run`) → open the Agent Inspector → deploy +6. Any sample-specific deep-dive sections (customization, advanced demos, reference) +7. Troubleshooting +8. Next steps + +## Conventions worth keeping + +- Prefer the current CLI commands (the template reflects these; avoid older + forms such as `azd ext install azure.ai.agents`). +- Prefer self-contained READMEs over deferring run/deploy steps to a parent + README or hiding steps inside collapsible `
` blocks. + +## When a sample legitimately differs + +Not every sample fits the two-option shape, and that's fine — adapt rather than +force it: + +- **Command-line-only samples** (e.g. VoiceLive, WebSocket, some A2A samples) may + have no VS Code / Agent Inspector path. Document the flow they actually support + (curl / `azd` / a browser client) and omit Option 2 when it doesn't apply. +- **Deploy-first samples** (e.g. A2A) may lead with deployment instead of a local + run. Keep the section order sensible for the scenario. + +Use the template for structure and shared vocabulary, and keep whatever +sample-specific sections a reader needs. + +> The per-sample `AGENTS.md` (hosted-agent overview, `azd` lifecycle, Microsoft +> Foundry Skill) still applies; this file only adds README conventions. diff --git a/samples/csharp/hosted-agents/README-template.md b/samples/csharp/hosted-agents/README-template.md new file mode 100644 index 000000000..970af5f11 --- /dev/null +++ b/samples/csharp/hosted-agents/README-template.md @@ -0,0 +1,151 @@ + + +# What this sample demonstrates + +{{One or two sentences: what the agent does and which framework it uses.}} + +## How it works + +{{Short description of how the agent is wired.}} See `Program.cs` for the implementation. + + + +## Prerequisites + +What the **sample itself** needs, independent of how you run it. The tooling for each run +path (`azd` or the VS Code Foundry Toolkit) is listed under its option below. + +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Roles (RBAC):** {{Azure roles the identity running the sample needs on the Foundry project or other resources, e.g. `Azure AI User`. Delete if project access is sufficient.}} +4. **Additional Azure resources:** {{Extra resources the sample depends on — a toolbox, connection, storage account, etc. If declared in the sample's `azure.yaml`, `azd provision` (Option 1) creates them; otherwise create them before running (Foundry portal, SDK, or `azd ai`). Delete if none.}} +5. **Environment variables / secrets:** {{Required env vars or secrets, e.g. `GITHUB_PAT`, and how to obtain them. Delete if none.}} + +## Option 1: Azure Developer CLI (`azd`) + +### Prerequisites + +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir my-agent && cd my-agent +azd ai agent init -m {{URL to your sample's azure.yaml on GitHub}} +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, from the project directory: + +```bash +azd ai agent invoke --local "{{prompt}}" +``` + +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "{{prompt}}" +``` + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `dotnet run` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + + + +## Troubleshooting + +> Delete if not needed. List errors specific to this sample and their fixes. + +{{Symptom → cause → fix.}} + +## Next steps + +- [Quickstart: Create a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent) +- {{Links to related samples.}} diff --git a/samples/csharp/hosted-agents/README.md b/samples/csharp/hosted-agents/README.md index 1b51731b1..c3fa9b050 100644 --- a/samples/csharp/hosted-agents/README.md +++ b/samples/csharp/hosted-agents/README.md @@ -252,7 +252,7 @@ Or, if you've already cloned this repository: ## Repo structure ``` -samples/dotnet/hosted-agents/ +samples/csharp/hosted-agents/ ├── agent-framework/ │ ├── hello-world/ ← Start here (Agent Framework) │ ├── simple-agent/ diff --git a/samples/csharp/hosted-agents/agent-framework/README.md b/samples/csharp/hosted-agents/agent-framework/README.md index b95b352a2..2e77ec710 100644 --- a/samples/csharp/hosted-agents/agent-framework/README.md +++ b/samples/csharp/hosted-agents/agent-framework/README.md @@ -141,22 +141,22 @@ Or in PowerShell:

Using the Foundry Toolkit VS Code Extension

 -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -The extension also adds an **Agent Inspector** UI for chatting with a hosted agent that is already running locally, plus a guided **Deploy Hosted Agent** command (see [Deploying the Agent to Foundry](#deploying-the-agent-to-foundry) below). +The [Foundry Toolkit VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio) has a built-in sample gallery. You can open a sample directly from the extension without cloning the repository — it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. It also adds an **Agent Inspector** UI for chatting with a running agent and a guided **Deploy Hosted Agent** command (see [Deploying the Agent to Foundry](#deploying-the-agent-to-foundry) below). #### Prerequisites -1. **Foundry Toolkit VS Code Extension** — [install from the VS Code marketplace](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=vscode) and sign in to Azure. -2. The agent is already running locally — start it with [`azd ai agent run`](#using-azd) or [`dotnet run`](#using-dotnet-run) first. +1. **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed and signed in to Azure. +2. **[C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)** extension. Run Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain. + +#### Run and debug the agent -#### Open the Agent Inspector +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -With the agent running on `http://localhost:8088/`: +#### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector auto-connects to the running agent. -3. Send messages from the Inspector to chat with the agent and watch the streamed responses. +1. Start the agent with [`azd ai agent run`](#using-azd) or [`dotnet run`](#using-dotnet-run) — it listens on `http://localhost:8088/`. +2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. +3. The Inspector auto-connects to the running agent. Send messages to chat and watch the streamed responses.
diff --git a/samples/csharp/hosted-agents/agent-framework/agent-skills/README.md b/samples/csharp/hosted-agents/agent-framework/agent-skills/README.md index 9547daaf3..a7da4e138 100644 --- a/samples/csharp/hosted-agents/agent-framework/agent-skills/README.md +++ b/samples/csharp/hosted-agents/agent-framework/agent-skills/README.md @@ -44,31 +44,13 @@ The agent is hosted using the [Agent Framework](https://github.com/microsoft/age See [Program.cs](src/agent-skills/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. - -### Required RBAC +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Roles (RBAC):** your identity (or the Managed Identity running the container in production) needs **Azure AI User** on the Foundry project scope. This single role covers both authoring skills and downloading them. -Your identity (or the Managed Identity running the container in production) needs **Azure AI User** on the Foundry project scope. This single role covers both authoring skills and downloading them. - -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -78,71 +60,60 @@ Your identity (or the Managed Identity running the container in production) need | `PROVISION_SAMPLE_SKILLS` | No | Sample convenience: set to `true` on a first run to upload this sample's `SKILL.md` files to Foundry. Leave unset or false in production. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -export SKILL_NAMES="support-style,escalation-policy" -export PROVISION_SAMPLE_SKILLS=true # First run only -``` +## Option 1: Azure Developer CLI (`azd`) -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +### Prerequisites -### Installing Dependencies +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). + ```bash + azd ext install microsoft.foundry + ``` -```bash -dotnet restore -``` +3. Authenticate: -### Running the Sample + ```bash + azd auth login + ``` -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry VS Code extension. +### Initialize the agent project -
-

Using the Foundry VS Code Extension

 +No cloning required. Create a new folder and initialize from the manifest: -The [Foundry VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository — it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +```bash +mkdir agent-skills && cd agent-skills +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/agent-skills/azure.yaml +``` -Follow the [VS Code quickstart](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) for a full step-by-step walkthrough. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir agent-skills && cd agent-skills - -# Initialize from the manifest - azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment. -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/agent-skills/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights). azd provision +``` -# Tell azd which skills to download at startup. -azd env set SKILL_NAMES "support-style,escalation-policy" +Tell azd which skills to download at startup, and (first run only) upload the sample's `SKILL.md` files to Foundry: -# First run only - upload the sample's local SKILL.md files to Foundry. +```bash +azd env set SKILL_NAMES "support-style,escalation-policy" azd env set PROVISION_SAMPLE_SKILLS true +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup). +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/agent-skills/azure.yaml` - -On startup you should see: +The agent host will start on `http://localhost:8088`. On startup you should see: ```text Skill 'support-style' already exists in Foundry. @@ -151,7 +122,9 @@ Downloading skill 'support-style' from Foundry... Downloading skill 'escalation-policy' from Foundry... ``` -The agent starts on `http://localhost:8088/`. To invoke it: +### Invoke the local agent + +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "Hi, I am Alex. Can I return my tent within 30 days?" @@ -172,44 +145,70 @@ curl -sS -X POST http://localhost:8088/responses \ Because skills are loaded on demand, the canary token in a response also proves the model actually invoked `load_skill` for the matching skill — not just saw its name in the advertised list. -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Make sure `SKILL_NAMES` is set in your azd environment so it is injected into the hosted container, then deploy to Microsoft Foundry: ```bash -dotnet run +azd env set SKILL_NAMES "support-style,escalation-policy" +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you have tested locally, deploy to Microsoft Foundry: +> The `skills/` source folder is **not** consumed by the deployed agent at runtime — only the skills already present in Foundry are downloaded. The provisioning step (or your own pipeline) must have uploaded the named skills to the same Foundry project before the agent starts. + +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup). -azd provision +azd ai agent invoke "Hi, I am Alex. Can I return my tent within 30 days?" +``` -# Make sure SKILL_NAMES is set in your azd environment so it is injected into the hosted container. -azd env set SKILL_NAMES "support-style,escalation-policy" +Stream logs from the running agent with `azd ai agent monitor`. -# Build, push, and deploy the agent to Foundry. -azd deploy -``` +## Option 2: VS Code (Foundry Toolkit) -After deploying, invoke the agent running in Foundry: +### Prerequisites -```bash -azd ai agent invoke "Hi, I am Alex. Can I return my tent within 30 days?" -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -To stream logs from the running agent: +### Run and debug the agent -```bash -azd ai agent monitor -``` +Set `SKILL_NAMES` (and `PROVISION_SAMPLE_SKILLS=true` on a first run) in `.env`, then press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -> The `skills/` source folder is **not** consumed by the deployed agent at runtime — only the skills already present in Foundry are downloaded. The provisioning step (or your own pipeline) must have uploaded the named skills to the same Foundry project before the agent starts. +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the [required variables](#environment-variables) (including `SKILL_NAMES`, plus `PROVISION_SAMPLE_SKILLS=true` on a first run). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/azure-search-rag/README.md b/samples/csharp/hosted-agents/agent-framework/azure-search-rag/README.md index 21d02ac9f..8219de150 100644 --- a/samples/csharp/hosted-agents/agent-framework/azure-search-rag/README.md +++ b/samples/csharp/hosted-agents/agent-framework/azure-search-rag/README.md @@ -17,27 +17,13 @@ The agent uses a `TextSearchProvider` wired to an `Azure.Search.Documents.Search See [Program.cs](src/azure-search-rag/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Additional Azure resources:** an Azure AI Search service with a populated index. `azd provision` (Option 1) can create the search service; the index must exist before the first run — see [Provisioning the search index](#provisioning-the-search-index). -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project, model deployment, or Azure AI Search service to get started, `azd provision` creates them all for you. If you already have some of these, see the [note below](#using-azd) on how to target them. - -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -47,71 +33,41 @@ Before running this sample, ensure you have: | `AZURE_SEARCH_INDEX_NAME` | Yes | Search index name. Defaults to `contoso-outdoors`. **Must exist before the agent starts** (see [Provisioning the search index](#provisioning-the-search-index)). | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** - -```bash -# Set env vars directly. .NET does not natively read .env files. -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -export AZURE_SEARCH_ENDPOINT="https://.search.windows.net" -export AZURE_SEARCH_INDEX_NAME="contoso-outdoors" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically. No manual setup needed. - -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically. Skip to [Running the Sample](#running-the-sample). - -Dependencies are restored automatically when building the project: +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -dotnet restore -``` - -### Running the Sample - -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. +## Option 1: Azure Developer CLI (`azd`) -
-

Using the Foundry Toolkit VS Code Extension

 +### Prerequisites -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -Chat with a running agent using the **Agent Inspector**: + ```bash + azd ext install microsoft.foundry + ``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +3. Authenticate: -
+ ```bash + azd auth login + ``` -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Initialize the agent project -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample, adopts its `azure.yaml` as the project manifest and configures your environment: +No cloning required. Create a new folder and initialize from the manifest: ```bash -# Create a new folder for the agent and navigate into it mkdir azure-search-rag-agent && cd azure-search-rag-agent - -# Initialize from the manifest. azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/azure-search-rag/azure.yaml +``` -# IMPORTANT: apply the storage workaround documented below before provisioning. - -# Provision Azure resources (Foundry project, model deployment, Azure AI Search, storage, App Insights) -azd provision +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, model deployment, or Azure AI Search service, `azd provision` creates them all for you. -# Run the agent locally (handles env vars, build, and startup) -azd ai agent run -``` +> If you already have a Foundry project, model deployment, and Azure AI Search service, add `-p -d ` to `azd ai agent init` to target existing resources. -##### Provisioning workaround: storage dependency +#### Provisioning workaround: storage dependency -The starter's Azure AI Search bicep module currently requires a co-provisioned storage account, but `azd ai agent init` only auto-prompts for `azure_ai_search` and `bing_grounding` tool resources. After running `init`, open the generated `azure.yaml` and add a `storage` entry to the agent service's `resources:` array so both resources get provisioned together: +The starter's Azure AI Search bicep module currently requires a co-provisioned storage account, but `azd ai agent init` only auto-prompts for `azure_ai_search` and `bing_grounding` tool resources. After running `init` and **before provisioning**, open the generated `azure.yaml` and add a `storage` entry to the agent service's `resources:` array so both resources get provisioned together: ```yaml services: @@ -126,14 +82,27 @@ services: Tracking issue: [Azure-Samples/azd-ai-starter-basic — make storage optional in azure_ai_search.bicep or auto-prompt](https://github.com/Azure-Samples/azd-ai-starter-basic/issues). -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/azure-search-rag/azure.yaml` +### Provision Azure resources (if needed) -> [!NOTE] -> If you already have a Foundry project, model deployment, and Azure AI Search service, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually, see [Manual setup](#manual-setup). +If you don't already have a Foundry project, model deployment, and Azure AI Search service (and after applying the storage workaround above): + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +> The search index must exist before the agent starts — see [Provisioning the search index](#provisioning-the-search-index). -The agent starts on `http://localhost:8088/`. To invoke it: +### Invoke the local agent + +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "What is your return policy?" @@ -155,53 +124,66 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "How do I clean my tent?", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "What is your return policy?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "What is your return policy?" -``` +## Option 2: VS Code (Foundry Toolkit) -To stream logs from the running agent: +### Prerequisites -```bash -azd ai agent monitor -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the [required variables](#environment-variables) (including `AZURE_SEARCH_ENDPOINT` and `AZURE_SEARCH_INDEX_NAME`). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Provisioning the search index diff --git a/samples/csharp/hosted-agents/agent-framework/browser-automation/README.md b/samples/csharp/hosted-agents/agent-framework/browser-automation/README.md index 4f94fb5e3..996c48ca6 100644 --- a/samples/csharp/hosted-agents/agent-framework/browser-automation/README.md +++ b/samples/csharp/hosted-agents/agent-framework/browser-automation/README.md @@ -99,107 +99,149 @@ The Toolbox endpoint is resolved as `/toolboxes//.env`; the sample's root `.env` file is only for local execution. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -### Local setup +### Prerequisites -Install dependencies and run the hosted-agent server locally: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore browser-automation.csproj -npm install -g @playwright/cli@latest -playwright-cli install --skills -dotnet run --project browser-automation.csproj -``` + ```bash + azd ext install microsoft.foundry + ``` -## Interacting with the agent +3. Authenticate: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](../../README.md) for more details. + ```bash + azd auth login + ``` -Send a POST request to the server with a JSON body containing an `"input"` field: +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "Open https://example.com and report the page title."}' +mkdir browser-automation-agent && cd browser-automation-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/browser-automation/azure.yaml ``` -Or in PowerShell: +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -```powershell -(Invoke-WebRequest ` - -Uri http://localhost:8088/responses ` - -Method POST ` - -ContentType "application/json" ` - -Body '{"input": "Open https://example.com and report the page title."}').Content -``` +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment, provision them. This sample also needs a Foundry Toolbox wired to an Azure Playwright workspace connection — choose one setup path: -With `azd`: +**Provision the toolbox with this sample** — set the Playwright workspace values in your `azd` environment (see [Provisioning parameters](#provisioning-parameters)), then provision. `azd provision` creates the Foundry connection to your Azure Playwright workspace and the default `browser-automation-tools` toolbox: ```bash -azd ai agent invoke --local --new-session "Open https://example.com and report the page title." +azd env set PLAYWRIGHT_SERVICE_URL "wss://.api.playwright.microsoft.com/playwrightworkspaces//browsers" +azd env set PLAYWRIGHT_SERVICE_RESOURCE_ID "/subscriptions//resourceGroups//providers/Microsoft.LoadTestService/playwrightWorkspaces/" +azd env set PLAYWRIGHT_SERVICE_ACCESS_TOKEN "" +azd provision ``` -The server returns a response ID that you can use to continue the same conversation and reuse the browser session in later requests: +> If these values are not set, `azd ai agent init` prompts you to enter them interactively. + +**Use an existing toolbox** — if your Foundry project already has a compatible toolbox (it must include the `browser_automation_preview` tool and its Playwright workspace connection), skip `azd provision` and set only the runtime toolbox name: ```bash -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "Now take a screenshot of the page.", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}' +azd env set TOOLBOX_NAME "" ``` -### Test in Agent Inspector +You don't need to set `TOOLBOX_NAME` when using the default sample-provisioned toolbox name, `browser-automation-tools`. -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Run the agent locally -Type the following message in Inspector: - -```text -Open https://example.com and report the page title. +```bash +azd ai agent run ``` -## Deploying the Agent to Foundry +The agent host will start on `http://localhost:8088`. -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](../../README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +### Invoke the local agent -Choose one toolbox setup path: +In a separate terminal, send a browser-automation request: -### Option 1: Let this sample provision the toolbox +```bash +azd ai agent invoke --local --new-session "Open https://example.com and report the page title." +``` -Use this path if you want `azd provision` to create the Foundry project connection to your Azure Playwright workspace and the default `browser-automation-tools` toolbox. +Or use curl directly: -Set the Playwright workspace values in your `azd` environment: +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Open https://example.com and report the page title."}' +``` + +The server returns a response ID you can use to continue the same conversation and reuse the browser session in later requests: ```bash -azd env set PLAYWRIGHT_SERVICE_URL "wss://.api.playwright.microsoft.com/playwrightworkspaces//browsers" -azd env set PLAYWRIGHT_SERVICE_RESOURCE_ID "/subscriptions//resourceGroups//providers/Microsoft.LoadTestService/playwrightWorkspaces/" -azd env set PLAYWRIGHT_SERVICE_ACCESS_TOKEN "" +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Now take a screenshot of the page.", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}' ``` -If these are not set, running `azd ai agent init -m ` will prompt you to enter them interactively. +### Deploy to Foundry -Run `azd provision` before `azd deploy`: +Once the toolbox is set up (see [Provision Azure resources](#provision-azure-resources-if-needed) above), deploy to Microsoft Foundry: ```bash -azd provision +azd deploy ``` -### Option 2: Use an existing toolbox +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Use this path if your Foundry project already has a compatible toolbox. You can skip `azd provision` and set only the runtime toolbox name used by the deployed hosted agent. The toolbox must include the `browser_automation_preview` tool and its Playwright workspace connection. +### Invoke the deployed agent ```bash -azd env set TOOLBOX_NAME "" +azd ai agent invoke --new-session "Open https://example.com and report the page title." ``` -You do not need to set `TOOLBOX_NAME` when using the default sample-provisioned toolbox name, `browser-automation-tools`. +## Option 2: VS Code (Foundry Toolkit) -Then deploy the hosted agent: +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +The agent shells out to the Playwright CLI, so install it once before running: ```bash -azd deploy +npm install -g @playwright/cli@latest +playwright-cli install --skills ``` +Then press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the runtime environment variables (see [Configuration](#configuration)) and sign in to Azure with the Azure CLI (`az login`). +2. Install dependencies and start the agent: + + ```bash + dotnet restore browser-automation.csproj + npm install -g @playwright/cli@latest + playwright-cli install --skills + dotnet run --project browser-automation.csproj + ``` + + The agent listens on `http://localhost:8088`. +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +Complete the toolbox setup in [Provision Azure resources](#provision-azure-resources-if-needed), then: + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + ## Customize the sample - Change prompt behavior in `prompts/base.md`. diff --git a/samples/csharp/hosted-agents/agent-framework/file-tools/README.md b/samples/csharp/hosted-agents/agent-framework/file-tools/README.md index 4a9394447..6a4eb62e6 100644 --- a/samples/csharp/hosted-agents/agent-framework/file-tools/README.md +++ b/samples/csharp/hosted-agents/agent-framework/file-tools/README.md @@ -26,27 +26,12 @@ Failures return a controlled `"File '' not found in ."` rather tha See [Program.cs](src/file-tools/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. - -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -56,74 +41,59 @@ Before running this sample, ensure you have: | `HOME` | No | The per-session sandbox volume root the session-files tools read from. Set by the Foundry platform; can be overridden for local testing. Defaults to `/home/session`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. - -### Installing Dependencies +## Option 1: Azure Developer CLI (`azd`) -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir file-tools-agent && cd file-tools-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/file-tools/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir file-tools-agent && cd file-tools-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/file-tools/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/file-tools/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. +This sample reads from two file sources — try each from a separate terminal. -##### Try the bundled-files path +**Bundled-files path:** ```bash azd ai agent invoke --local "What is the headline total revenue in the contoso file?" @@ -131,9 +101,7 @@ azd ai agent invoke --local "What is the headline total revenue in the contoso f The agent calls `ListBundledFiles`, finds `contoso_q1_2026_report.txt`, calls `ReadBundledFile("contoso_q1_2026_report.txt")` (rooted at `/app/resources/`), and quotes the figure verbatim (`$1,482.6M`). -##### Try the session-files path - -Upload the included demo file to the same session, then ask about it. `azd ai agent files upload` auto-resolves the session-id from the last invocation: +**Session-files path** — upload the included demo file to the same session, then ask about it. `azd ai agent files upload` auto-resolves the session-id from the last invocation: ```bash azd ai agent files upload ./example-upload/user_notes.txt @@ -142,7 +110,7 @@ azd ai agent invoke --local "What magic token is in user_notes.txt?" The agent calls `ListSessionFiles`, finds `user_notes.txt`, calls `ReadSessionFile("user_notes.txt")` (rooted at `$HOME`), and quotes the token. -##### Try a traversal attempt (it should be refused) +**Traversal attempt (it should be refused):** ```bash azd ai agent invoke --local "Read the file at the path '../../../etc/passwd' from the bundled files." @@ -150,29 +118,17 @@ azd ai agent invoke --local "Read the file at the path '../../../etc/passwd' fro The agent's tool schema only accepts a `fileName` (no `path`), and the `Path.GetFileName` + `StartsWith(root)` defence in depth rejects anything that resolves outside the tool's root. The agent will refuse and explain that only the bundled files are available. -#### Manual setup - -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +### Deploy to Foundry -```bash -dotnet run -``` - -You can then upload session files via raw HTTP if needed (see [`POST /agents/{name}/endpoint/sessions/{id}/files/content`](https://learn.microsoft.com/en-us/azure/foundry/agents/) in the Foundry SDK docs). - -### Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent ```bash azd ai agent invoke "What is the headline total revenue in the contoso file?" @@ -180,27 +136,52 @@ azd ai agent files upload ./example-upload/user_notes.txt azd ai agent invoke "What magic token is in user_notes.txt?" ``` -To stream logs from the running agent: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent monitor -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + + You can upload session files via raw HTTP if needed (see [`POST /agents/{name}/endpoint/sessions/{id}/files/content`](https://learn.microsoft.com/en-us/azure/foundry/agents/) in the Foundry SDK docs). + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Adding more bundled files diff --git a/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/README.md b/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/README.md index 067888740..85a182843 100644 --- a/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/README.md +++ b/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/README.md @@ -16,27 +16,12 @@ The store is created on startup via `EnsureMemoryStoreCreatedAsync` (idempotent) See [Program.cs](src/foundry-memory-rag/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started, `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with **chat and embedding model deployments** (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -46,73 +31,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MEMORY_STORE_ID` | No | Memory store name. Defaults to `foundry-memory-rag-store`. The store is created on startup if it does not exist. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly. .NET does not natively read .env files. -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -export AZURE_AI_EMBEDDING_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically. No manual setup needed. - -### Installing Dependencies +## Option 1: Azure Developer CLI (`azd`) -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically. Skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir foundry-memory-rag-agent && cd foundry-memory-rag-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployments. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployments, add `-p -d ` to `azd ai agent init` to target existing resources. You also need an embedding deployment (default `text-embedding-3-small`); set its name via `AZURE_AI_EMBEDDING_DEPLOYMENT_NAME` if it differs from the default. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample, adopts its `azure.yaml` as the project manifest and configures your environment: +If you don't already have a Foundry project and model deployments: ```bash -# Create a new folder for the agent and navigate into it -mkdir foundry-memory-rag-agent && cd foundry-memory-rag-agent - -# Initialize from the manifest. azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/azure.yaml - -# Provision Azure resources (Foundry project, chat + embedding deployments, App Insights) azd provision +``` -# Run the agent locally (handles env vars, build, and startup) +### Run the agent locally + +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployments, add `-p -d ` to `azd ai agent init` to target existing resources. You also need an embedding deployment (default `text-embedding-3-small`); set its name via `AZURE_AI_EMBEDDING_DEPLOYMENT_NAME` if it differs from the default. +### Invoke the local agent -The agent starts on `http://localhost:8088/`. Run a few turns to seed memory, then ask the agent to recall: +Run a few turns to seed memory, then ask the agent to recall: ```bash azd ai agent invoke --local "Remember that I want to run my first 5k in October and I prefer morning workouts." @@ -132,52 +101,68 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "What do you already know about my training goals?", "stream": false}' | jq . ``` -Memory extraction is asynchronous server-side, expect a few seconds between the teaching turn and the recall turn. +Memory extraction is asynchronous server-side — expect a few seconds between the teaching turn and the recall turn. -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry (this also runs provisioning if needed): ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Build, push, and deploy the agent to Foundry (also runs provisioning if needed) -azd deploy +azd ai agent invoke "What do you already know about my training goals?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "What do you already know about my training goals?" -``` +## Option 2: VS Code (Foundry Toolkit) -To stream logs from the running agent: +### Prerequisites -```bash -azd ai agent monitor -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the [required variables](#environment-variables) (including `AZURE_AI_EMBEDDING_DEPLOYMENT_NAME`). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills/README.md b/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills/README.md index f38583439..c781b22e2 100644 --- a/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills/README.md +++ b/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills/README.md @@ -20,66 +20,136 @@ See [Program.cs](src/foundry-toolbox-mcp-skills/Program.cs) for the full impleme ## Prerequisites -Before running this sample, ensure you have: +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **A Foundry Toolbox with MCP-based skills** — a [Foundry Toolbox](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) with at least one [skill](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/skills?pivots=dotnet) attached. This sample only consumes skills from an existing toolbox — it does not create or provision them. -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) and the AI agent extension: `azd ext install azure.ai.agents` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -4. **A Foundry Toolbox with MCP-based skills** - - A [Foundry Toolbox](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) with at least one [skill](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/skills?pivots=dotnet) attached. Skills are authored through the Skills API and attached to a toolbox version so that any MCP client can discover and load them. - -> [!NOTE] -> This sample only consumes skills from an existing toolbox - it does not create or provision them. - -## Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| | `FOUNDRY_PROJECT_ENDPOINT` | Yes | Foundry project endpoint. | -| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name - must match a deployment in your Foundry project. | +| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match a deployment in your Foundry project. | | `TOOLBOX_NAME` | Yes | Name of the Foundry Toolbox to connect to. The toolbox must already be provisioned with MCP-based skills. | -> [!NOTE] -> Values for these environment variables are provided by the `azd ai agent init` command. +Values for these are provided by the `azd ai agent init` command (Option 1) or the Foundry Toolkit scaffold (Option 2). + +## Option 1: Azure Developer CLI (`azd`) + +### Prerequisites -## Running Locally +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -For instructions on running this sample locally, see the [parent README](../README.md). + ```bash + azd ext install microsoft.foundry + ``` -## Deploying the Agent to Microsoft Foundry +3. Authenticate: -The quickest path to deploy this sample to Microsoft Foundry: + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -# Create a new folder for the agent and navigate into it mkdir foundry-toolbox-mcp-skills && cd foundry-toolbox-mcp-skills - -# Initialize from the manifest - azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment. azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills/azure.yaml +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) -# Provision Azure resources, build, push, and deploy the agent to Foundry. -azd up +If you don't already have a Foundry project and model deployment: + +```bash +azd provision ``` -After deploying, invoke the agent running in Foundry: +### Run the agent locally ```bash -azd ai agent invoke "What skills do you have available?" +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, invoke the running agent: + +```bash +azd ai agent invoke --local "What skills do you have available?" ``` -To stream logs from the running agent: +Or use curl directly: ```bash -azd ai agent monitor +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What skills do you have available?", "stream": false}' ``` -For additional deployment options (Foundry VS Code extension, deploying from a local clone, etc.), see the [parent README](../README.md). For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "What skills do you have available?" +``` + +Stream logs from the running agent with `azd ai agent monitor`. + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the [required variables](#environment-variables) (including `TOOLBOX_NAME`). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/README.md b/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/README.md index d9d514438..24dddcf1c 100644 --- a/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/README.md +++ b/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/README.md @@ -12,13 +12,65 @@ You can also create a Foundry Toolbox in the Foundry portal. Read more about it > If you set up a project with this sample and provision the resources using `azd provision`, a Foundry Toolbox will be created with the tools declared in [`azure.yaml`](azure.yaml) — by default, `code_interpreter` (server-side code execution) plus an `mcp` tool pointing at the public `https://gitmcp.io/Azure/azure-rest-api-specs` MCP server. Swap either out for any other toolbox tool type that fits your scenario. -## Running the Agent Host +## Prerequisites -Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **A Foundry Toolbox** exposing the server-side tools (see [Creating a Foundry Toolbox](#creating-a-foundry-toolbox) above). If declared in the sample's `azure.yaml`, `azd provision` (Option 1) creates it. -## Interacting with the agent +## Option 1: Azure Developer CLI (`azd`) -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell), `azd`, or the **Agent Inspector** in the Foundry Toolkit VS Code extension. Please refer to the [parent README](../README.md) for more details. Use this README for sample queries you can send to the agent. +### Prerequisites + +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir foundry-toolbox-agent && cd foundry-toolbox-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/azure.yaml +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project, model deployment, and toolbox, provision them: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, ask the agent about its toolbox tools: + +```bash +azd ai agent invoke --local "What tools do you have?" +``` + +Or use curl directly: ```bash curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What tools do you have?", "stream": false}' @@ -26,31 +78,62 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Use the code interpreter to compute the 30th Fibonacci number.", "stream": false}' ``` -### Test in Agent Inspector - -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Deploy to Foundry -Type the following message in Inspector: +Once tested locally, deploy to Microsoft Foundry: +```bash +azd deploy ``` -What tools do you have? + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "What tools do you have?" ``` -## Deploying the Agent to Foundry +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the required variables (including `TOOLBOX_NAME`). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` -To deploy the agent to Foundry, follow the instructions in the [Deploying the Agent to Foundry](../README.md#deploying-the-agent-to-foundry) section of the parent README. +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/csharp/hosted-agents/agent-framework/hello-world/README.md b/samples/csharp/hosted-agents/agent-framework/hello-world/README.md index 6c48f4e0c..d97533376 100644 --- a/samples/csharp/hosted-agents/agent-framework/hello-world/README.md +++ b/samples/csharp/hosted-agents/agent-framework/hello-world/README.md @@ -2,62 +2,137 @@ A minimal "hello world" hosted agent using the [Agent Framework](https://github.com/microsoft/agent-framework) with the Responses protocol in C#. This is the recommended starting point for understanding how agents are hosted on Foundry. -## Running the Agent Host +## Prerequisites -Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -## Interacting with the agent +## Option 1: Azure Developer CLI (`azd`) -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell), `azd`, or the **Agent Inspector** in the Foundry Toolkit VS Code extension. Please refer to the [parent README](../README.md) for more details. Use this README for sample queries you can send to the agent. +### Prerequisites -Send a request to the agent: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -azd ai agent invoke --local "What is Microsoft Foundry?" +mkdir hello-world-agent && cd hello-world-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/hello-world/azure.yaml ``` -Or use `curl`: +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: ```bash -curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What is Microsoft Foundry?", "stream": false}' +azd provision ``` -The server will respond with a JSON object containing the response text and a response ID. You can use this response ID to continue the conversation in subsequent requests. +### Run the agent locally -### Multi-turn conversation +```bash +azd ai agent run +``` -To have a multi-turn conversation with the agent, include the previous response id in the request body: +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, send a request to the agent: ```bash -curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Can you summarize that?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID", "stream": false}' +azd ai agent invoke --local "What is Microsoft Foundry?" +``` + +Or use curl directly: + +```bash +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What is Microsoft Foundry?", "stream": false}' ``` -### Test in Agent Inspector +The server responds with a JSON object containing the response text and a response ID. Continue the conversation by passing that ID as `previous_response_id`: + +```bash +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Can you summarize that?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID", "stream": false}' +``` -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Deploy to Foundry -Type the following message in Inspector: +Once tested locally, deploy to Microsoft Foundry: +```bash +azd deploy ``` -What is Microsoft Foundry? + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "What is Microsoft Foundry?" ``` -## Deploying the Agent to Foundry +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Set the required environment variables: + + ```bash + export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="" + ``` + +3. Sign in to Azure with the Azure CLI: + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` -To deploy the agent to Foundry, follow the instructions in the [Deploying the Agent to Foundry](../README.md#deploying-the-agent-to-foundry) section of the parent README. +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/README.md b/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/README.md index 4bf1a7825..e7a1629d7 100644 --- a/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/README.md +++ b/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/README.md @@ -8,27 +8,11 @@ The agent registers a custom `EchoAIAgent` that implements the Invocations proto See [Program.cs](src/invocations-echo-agent/Program.cs) and [EchoAIAgent.cs](src/invocations-echo-agent/EchoAIAgent.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> This sample does **not** call an LLM, so you do **not** need a Foundry project or model deployment. However, `azd provision` is still available if you want to set up infrastructure for deployment. +1. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. This sample does **not** call an LLM, so no Foundry project or model deployment is required — though `azd provision` (Option 1) is still available if you want to set up infrastructure for deployment. -### Environment Variables +### Environment variables This agent does **not** require a model deployment — no `FOUNDRY_PROJECT_ENDPOINT` or `AZURE_AI_MODEL_DEPLOYMENT_NAME` is needed. @@ -36,71 +20,64 @@ This agent does **not** require a model deployment — no `FOUNDRY_PROJECT_ENDPO |----------|----------|-------------| | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Optional | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +When using `azd ai agent run`, these are handled automatically. -### Installing Dependencies +## Option 1: Azure Developer CLI (`azd`) -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir echo-agent && cd echo-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your project. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one (not required for this LLM-free sample, but useful for deployment). -
+> If you already have a Foundry project, add `-p ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +Only needed if you plan to deploy: ```bash -# Create a new folder for the agent and navigate into it -mkdir echo-agent && cd echo-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/azure.yaml - -# Provision Azure resources (Foundry project, App Insights) azd provision +``` -# Run the agent locally (handles env vars, build, and startup) +### Run the agent locally + +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/invocations-echo-agent/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project, add `-p ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: -**Bash:** ```bash azd ai agent invoke --local '{"message": "Hello, world!"}' ``` -**PowerShell:** +In PowerShell: + ```powershell azd ai agent invoke --local '{\"message\": \"Hello, world!\"}' ``` @@ -113,7 +90,7 @@ curl -X POST http://localhost:8088/invocations -i \ -d '{"message": "Hello, world!"}' ``` -The server will respond with a JSON object containing the response text. The `-i` flag includes the HTTP response headers in the output, which includes the session ID that can be used for multi-turn conversations. Here is an example of the response: +The server responds with a JSON object containing the response text. The `-i` flag includes the HTTP response headers, which include the session ID used for multi-turn conversations: ``` HTTP/1.1 200 @@ -125,9 +102,7 @@ x-platform-server: azure-ai-agentserver-core/2.0.0 (dotnet/10.0) {"response":"Echo: Hello, world!"} ``` -### Multi-turn conversation - -To have a multi-turn conversation with the agent, take the session ID from the response headers of the previous request and include it in URL parameters for the next request: +For a multi-turn conversation, take the session ID from the response headers and pass it as an `agent_session_id` URL parameter: ```bash curl -X POST "http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4436-a57f-03b843ac0e17" -i \ @@ -135,59 +110,64 @@ curl -X POST "http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4 -d '{"message": "How are you?"}' ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually if needed (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run -``` - -### Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: - -```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent -**Bash:** ```bash azd ai agent invoke '{"message": "Hello, world!"}' ``` -**PowerShell:** +In PowerShell: + ```powershell azd ai agent invoke '{\"message\": \"Hello, world!\"}' ``` -To stream logs from the running agent: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent monitor -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Start the agent (listens on `http://localhost:8088`) — this LLM-free sample needs no environment variables or Azure sign-in to run locally: + + ```bash + dotnet run + ``` + +3. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/local-tools/README.md b/samples/csharp/hosted-agents/agent-framework/local-tools/README.md index 082ab5055..3b8ad08db 100644 --- a/samples/csharp/hosted-agents/agent-framework/local-tools/README.md +++ b/samples/csharp/hosted-agents/agent-framework/local-tools/README.md @@ -8,27 +8,12 @@ The agent registers local C# functions as tools using `AIFunctionFactory.Create` See [Program.cs](src/local-tools/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -36,72 +21,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir local-tools-agent && cd local-tools-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/local-tools/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir local-tools-agent && cd local-tools-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/local-tools/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/local-tools/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "Find hotels in Seattle for Dec 20-25 under $200/night" @@ -115,53 +85,66 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "Find hotels in Seattle for Dec 20-25 under $200/night", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "Find hotels in Seattle for Dec 20-25 under $200/night" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "Find hotels in Seattle for Dec 20-25 under $200/night" -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites -To stream logs from the running agent: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -```bash -azd ai agent monitor -``` +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: create a `.env` file with the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/mcp-tools/README.md b/samples/csharp/hosted-agents/agent-framework/mcp-tools/README.md index 3ce21387a..5bacef982 100644 --- a/samples/csharp/hosted-agents/agent-framework/mcp-tools/README.md +++ b/samples/csharp/hosted-agents/agent-framework/mcp-tools/README.md @@ -8,27 +8,12 @@ The agent is configured with MCP tool providers that expose documentation search See [Program.cs](src/mcp-tools/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -36,72 +21,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir mcp-tools-agent && cd mcp-tools-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/mcp-tools/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir mcp-tools-agent && cd mcp-tools-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/mcp-tools/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/mcp-tools/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "Search Microsoft Learn for how to use dependency injection in ASP.NET Core" @@ -121,53 +91,66 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "Find a C# code sample for creating an Azure Blob Storage container", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "Search Microsoft Learn for how to use dependency injection in ASP.NET Core" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "Search Microsoft Learn for how to use dependency injection in ASP.NET Core" -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites -To stream logs from the running agent: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -```bash -azd ai agent monitor -``` +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: create a `.env` file with the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/observability/README.md b/samples/csharp/hosted-agents/agent-framework/observability/README.md index 6964ca0fe..7f3e9edd8 100644 --- a/samples/csharp/hosted-agents/agent-framework/observability/README.md +++ b/samples/csharp/hosted-agents/agent-framework/observability/README.md @@ -22,57 +22,136 @@ To include prompt and completion content in trace events, set the OpenTelemetry Foundry Hosted Agent has built-in observability, so you do not need to register exporters manually. The traces, metrics, and logs generated by the agent are automatically collected and made available through Foundry's observability stack via Azure Monitor and Application Insights. The `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable is injected when the agent is deployed to Foundry; for local runs that should still flow telemetry to Application Insights, set it in your environment. -## Running the Agent Host +## Prerequisites -Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Telemetry for local runs (optional):** Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` for deployed agents. To flow telemetry to Application Insights during local runs, set it in your environment. -## Interacting with the agent +## Option 1: Azure Developer CLI (`azd`) -> Because the observability exporters are managed by Foundry, this sample is best run using `azd ai agent run`. Running with `dotnet run` will start the agent locally, but telemetry will only be sent to Application Insights if you configure `APPLICATIONINSIGHTS_CONNECTION_STRING` yourself. +### Prerequisites + +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -azd ai agent run --local "What is the current weather?" +mkdir observability-agent && cd observability-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/observability/azure.yaml ``` -Several spans will be created for this request from Agent Framework's instrumentation: +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -- `invoke_agent`: This span represents the invocation of the agent itself, capturing the start and end of the agent's processing for this request. -- `chat`: This span represents the call to the underlying model. -- `execute_tool`: This span represents the execution of any tools invoked by the agent as part of generating the response. +### Provision Azure resources (if needed) -> For more information on the spans, refer to the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). +If you don't already have a Foundry project and model deployment: -### Test in Agent Inspector +```bash +azd provision +``` -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Run the agent locally -Type the following message in Inspector: +```bash +azd ai agent run +``` +The agent host will start on `http://localhost:8088`. + +> Because the observability exporters are managed by Foundry, this sample is best run with `azd ai agent run`. Running with `dotnet run` sends telemetry to Application Insights only if you set `APPLICATIONINSIGHTS_CONNECTION_STRING` yourself. + +### Invoke the local agent + +In a separate terminal, invoke the agent: + +```bash +azd ai agent invoke --local "What is the current weather?" ``` -What is the current weather? + +Several spans are created for this request from Agent Framework's instrumentation: + +- `invoke_agent`: the invocation of the agent itself, capturing the start and end of the agent's processing for this request. +- `chat`: the call to the underlying model. +- `execute_tool`: the execution of any tools invoked by the agent as part of generating the response. + +> For more information on the spans, refer to the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). + +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "What is the current weather?" ``` -## Deploying the Agent to Foundry +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](../README.md#deploying-the-agent-to-foundry) section of the parent README. +### Run and debug the agent -### Viewing Telemetry in Foundry +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -Once the agent is deployed to Foundry, the telemetry generated by the agent (traces, metrics, and logs) will be automatically collected and sent to Azure Monitor and Application Insights. You can view this telemetry by navigating to the Application Insights resource associated with your Foundry project or directly from the Foundry UI. +### Or run manually, then open the Inspector -In the Foundry UI, next to the **Playground** tab is the **Traces** tab, where you can find the conversations and their corresponding trace IDs. Clicking on a trace ID will allow you to drill into the detailed trace information for that particular conversation. +1. Restore dependencies: -### Deploying with the Foundry Toolkit VS Code Extension + ```bash + dotnet restore + ``` -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +2. Configure the agent: copy `.env.example` to `.env` and fill in the required variables (set `APPLICATIONINSIGHTS_CONNECTION_STRING` too for local telemetry). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + +## Viewing telemetry in Foundry + +Once the agent is deployed to Foundry, the telemetry generated by the agent (traces, metrics, and logs) is automatically collected and sent to Azure Monitor and Application Insights. View it by navigating to the Application Insights resource associated with your Foundry project, or directly from the Foundry UI. + +In the Foundry UI, next to the **Playground** tab is the **Traces** tab, where you can find the conversations and their corresponding trace IDs. Clicking on a trace ID lets you drill into the detailed trace information for that conversation. diff --git a/samples/csharp/hosted-agents/agent-framework/simple-agent/README.md b/samples/csharp/hosted-agents/agent-framework/simple-agent/README.md index af72635ba..e6195bf20 100644 --- a/samples/csharp/hosted-agents/agent-framework/simple-agent/README.md +++ b/samples/csharp/hosted-agents/agent-framework/simple-agent/README.md @@ -8,27 +8,12 @@ The agent registers a single AI agent with `AsAIAgent(model, instructions)` and See [Program.cs](src/simple-agent/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -36,72 +21,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir simple-agent && cd simple-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/simple-agent/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir simple-agent && cd simple-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/simple-agent/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/simple-agent/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "Hello! What can you help me with?" @@ -115,53 +85,66 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "Hello! What can you help me with?", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "Hello! What can you help me with?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "Hello! What can you help me with?" -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites -To stream logs from the running agent: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -```bash -azd ai agent monitor -``` +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: create a `.env` file with the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/teams-activity/README.md b/samples/csharp/hosted-agents/agent-framework/teams-activity/README.md index a8c5a46b0..10388604f 100644 --- a/samples/csharp/hosted-agents/agent-framework/teams-activity/README.md +++ b/samples/csharp/hosted-agents/agent-framework/teams-activity/README.md @@ -16,30 +16,136 @@ See [Program.cs](src/teams-activity-dotnet-agent-framework/Program.cs) for the f The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with `AgentHost.CreateBuilder()`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol. -## Running the Agent Host +## Prerequisites -Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Work IQ toolbox:** the agent answers Teams and calendar questions through a Work IQ toolbox. If declared in the sample's `azure.yaml`, `azd provision` (Option 1) creates it. -## Interacting with the agent +## Option 1: Azure Developer CLI (`azd`) -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](../README.md) for more details. Use this README for sample queries you can send to the agent. +### Prerequisites -Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How many meetings do I have tomorrow?"}' +mkdir teams-activity-agent && cd teams-activity-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/teams-activity/azure.yaml +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run ``` -The server will respond with a JSON object containing the response text and a response ID. You can use this response ID to continue the conversation in subsequent requests. +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent -### Multi-turn conversation +In a separate terminal, send a request to the agent: + +```bash +azd ai agent invoke --local "How many meetings do I have tomorrow?" +``` -To have a multi-turn conversation with the agent, include the previous response id in the request body. For example: +Or use curl directly: + +```bash +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How many meetings do I have tomorrow?"}' +``` + +The server responds with a JSON object containing the response text and a response ID. Continue the conversation by passing that ID as `previous_response_id`: ```bash curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How are you?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}' ``` +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "How many meetings do I have tomorrow?" +``` + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the required variables. The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + ## Publishing the Agent 1. In the Foundry portal, click **Publish**, then choose **Publish to Teams and Microsoft 365**. For the full flow, see this [documentation](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/publish-copilot). diff --git a/samples/csharp/hosted-agents/agent-framework/text-search-rag/README.md b/samples/csharp/hosted-agents/agent-framework/text-search-rag/README.md index 1996b3b35..2a568a85c 100644 --- a/samples/csharp/hosted-agents/agent-framework/text-search-rag/README.md +++ b/samples/csharp/hosted-agents/agent-framework/text-search-rag/README.md @@ -8,27 +8,12 @@ The agent uses a `TextSearchProvider` to search through a knowledge base of supp See [Program.cs](src/text-search-rag/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -36,72 +21,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir text-search-rag-agent && cd text-search-rag-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/text-search-rag/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir text-search-rag-agent && cd text-search-rag-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/text-search-rag/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/text-search-rag/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "What is your return policy?" @@ -123,53 +93,66 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "How do I clean my tent?", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "What is your return policy?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "What is your return policy?" -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites -To stream logs from the running agent: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -```bash -azd ai agent monitor -``` +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: create a `.env` file with the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/README.md b/samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/README.md index b5459e3ef..e84e2b89e 100644 --- a/samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/README.md +++ b/samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/README.md @@ -62,7 +62,7 @@ Path 2 is documented rather than wired by default because it needs a post-deploy The agent reads its toolbox from your Foundry project at startup, so the `auth-paths-tools` toolbox (and the `github-mcp-conn` connection that backs the key-based path) must exist in the project before you run. You have two ways to create them. -### Option 1 — `azd provision` (recommended) +### Provision with `azd` (recommended) `azd provision` reads [`azure.yaml`](azure.yaml) and creates the connection and toolbox for you: @@ -73,7 +73,7 @@ azd provision # creates github-mcp-conn (CustomKeys) + auth-paths-t The `gh_pat` value is stored only in the Foundry connection secret store. It is never written to disk or passed to the container as an env var. Use a GitHub PAT (classic `ghp_...` or fine-grained `github_pat_...`) scoped to read the repositories your prompts ask about. Public-repo read is enough for the sample prompts. -### Option 2 — create the toolbox yourself +### Create the toolbox yourself Create the same two resources in the [Foundry portal](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) or in code with the [Foundry Toolbox CRUD sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/hosted_agents/sample_toolboxes_crud.py): @@ -84,7 +84,7 @@ Once the toolbox exists, set `TOOLBOX_NAME=auth-paths-tools` (already the manife ## Continuous integration -The `hosted-agents-cloud-e2e` workflow treats this as a **toolbox sample** (its directory name contains `toolbox`) and runs with `SKIP_PROVISION=true`, so it does **not** run `azd provision` and never receives a PAT. Instead it consumes a toolbox that already exists in a shared Foundry project, the same way [`langgraph-toolbox`](../../../python/hosted-agents/bring-your-own/responses/langgraph-toolbox/) does. To enable it there, register an `auth-paths-tools` toolbox in that project (Option 2 above) and add one `label=url|query` line to the `TOOLBOX_ENDPOINT` repository variable: +The `hosted-agents-cloud-e2e` workflow treats this as a **toolbox sample** (its directory name contains `toolbox`) and runs with `SKIP_PROVISION=true`, so it does **not** run `azd provision` and never receives a PAT. Instead it consumes a toolbox that already exists in a shared Foundry project, the same way [`langgraph-toolbox`](../../../python/hosted-agents/bring-your-own/responses/langgraph-toolbox/) does. To enable it there, register an `auth-paths-tools` toolbox in that project (see [Create the toolbox yourself](#create-the-toolbox-yourself), above) and add one `label=url|query` line to the `TOOLBOX_ENDPOINT` repository variable: ``` auth-paths=https://.services.ai.azure.com/api/projects//toolboxes/auth-paths-tools/mcp?api-version=v1| @@ -92,13 +92,53 @@ auth-paths=https://.services.ai.azure.com/api/projects//toolbo The workflow derives `TOOLBOX_NAME` from the URL slug (`.../toolboxes/auth-paths-tools/mcp`) and drives the toolbox with that query. Until the toolbox is registered, add a `.ci-skip` file in this directory to keep the sample out of the gated set. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -With the agent host running locally on `http://localhost:8088/`, use `azd ai agent invoke --local` to send a prompt: + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir toolbox-auth-paths-agent && cd toolbox-auth-paths-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/azure.yaml +``` + +`azd ai agent init` prompts once for the `gh_pat` secret parameter. Follow the prompts to configure your Foundry project and model deployment. + +### Provision Azure resources (if needed) + +The agent reads its toolbox from your Foundry project at startup, so the `auth-paths-tools` toolbox and `github-mcp-conn` connection must exist first — see [Provisioning the toolbox in your environment](#provisioning-the-toolbox-in-your-environment). With the manifest, `azd provision` creates them (along with a Foundry project and model deployment if you don't have one): + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, send a prompt: ```bash azd ai agent invoke --local "What tools do you have available?" @@ -107,8 +147,68 @@ azd ai agent invoke --local "Search the microsoft/agent-framework repo for open A GitHub answer means the key-based **CustomKeys** path (path 1) resolved its PAT correctly. A `401`/`403` means the connection credential did not resolve. -> You can also invoke with `curl` (`Invoke-WebRequest` in PowerShell) against `http://localhost:8088/responses`, or use the **Agent Inspector** in the Foundry Toolkit VS Code extension. See the [parent README](../README.md) for details. +Or use curl directly against `http://localhost:8088/responses`: + +```bash +curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What tools do you have available?", "stream": false}' +``` + +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "What tools do you have available?" +``` + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +The `auth-paths-tools` toolbox must already exist (see [Provisioning the toolbox in your environment](#provisioning-the-toolbox-in-your-environment)). Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: copy `.env.example` to `.env` and fill in the required variables (including `TOOLBOX_NAME=auth-paths-tools`). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -## Deploying the Agent to Foundry +### Deploy to Foundry -To deploy the agent to Foundry, follow the instructions in the [Deploying the Agent to Foundry](../README.md#deploying-the-agent-to-foundry) section of the parent README. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/csharp/hosted-agents/agent-framework/workflows/README.md b/samples/csharp/hosted-agents/agent-framework/workflows/README.md index 4b288c74b..922205432 100644 --- a/samples/csharp/hosted-agents/agent-framework/workflows/README.md +++ b/samples/csharp/hosted-agents/agent-framework/workflows/README.md @@ -8,27 +8,12 @@ The workflow registers three translation agents — English→French, French→S See [Program.cs](src/workflows/Program.cs) for the full implementation. -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Required | Description | |----------|----------|-------------| @@ -36,72 +21,57 @@ Before running this sample, ensure you have: | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies - -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +### Prerequisites -Dependencies are restored automatically when building the project: +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -```bash -dotnet restore -``` + ```bash + azd ext install microsoft.foundry + ``` -### Running the Sample +3. Authenticate: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir workflows-agent && cd workflows-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/workflows/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir workflows-agent && cd workflows-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/agent-framework/workflows/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/csharp/hosted-agents/agent-framework/workflows/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "The quick brown fox jumps over the lazy dog" @@ -117,53 +87,66 @@ curl -sS -X POST http://localhost:8088/responses \ Expected output: three lines showing the text in French, Spanish, then back in English. -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "The quick brown fox jumps over the lazy dog" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "The quick brown fox jumps over the lazy dog" -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites -To stream logs from the running agent: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -```bash -azd ai agent monitor -``` +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Configure the agent: create a `.env` file with the [required variables](#environment-variables). The sample loads `.env` automatically on startup. + +3. Sign in to Azure with the Azure CLI so `DefaultAzureCredential` can authenticate the terminal process (the **F5** path reuses the Azure sign-in from the Foundry Toolkit, so it doesn't need a separate `az login`): + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/bring-your-own/invocations/HelloWorld/README.md b/samples/csharp/hosted-agents/bring-your-own/invocations/HelloWorld/README.md index 92191109e..4549448aa 100644 --- a/samples/csharp/hosted-agents/bring-your-own/invocations/HelloWorld/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/invocations/HelloWorld/README.md @@ -32,27 +32,12 @@ The agent is hosted using the [Azure AI AgentServer Invocations SDK](https://www The hosted agent can be developed and deployed to Microsoft Foundry using the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd). -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables See [`.env.example`](src/hello-world-dotnet-invocations/.env.example) or `.env` for the full list of environment variables this sample uses. @@ -62,69 +47,64 @@ See [`.env.example`](src/hello-world-dotnet-invocations/.env.example) or `.env` | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` +## Option 1: Azure Developer CLI (`azd`) -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +### Prerequisites -### Running the Sample +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. + ```bash + azd ext install microsoft.foundry + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +3. Authenticate: -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. + ```bash + azd auth login + ``` -Chat with a running agent using the **Agent Inspector**: +### Initialize the agent project -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +No cloning required. Create a new folder and initialize from the manifest: -
+```bash +mkdir hello-world-agent && cd hello-world-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/invocations/HelloWorld/azure.yaml +``` -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -```bash -# Create a new folder for the agent and navigate into it -mkdir hello-world-agent && cd hello-world-agent +### Provision Azure resources (if needed) -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/dotnet/hosted-agents/bring-your-own/invocations/HelloWorld/azure.yaml +If you don't already have a Foundry project and model deployment: -# Provision Azure resources (Foundry project, model deployment, App Insights) +```bash azd provision +``` -# Run the agent locally (handles env vars, build, and startup) +### Run the agent locally + +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/dotnet/hosted-agents/bring-your-own/invocations/HelloWorld/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "What is Microsoft Foundry?" ``` -Or use curl directly. The `-N` flag disables output buffering so you see SSE tokens as they arrive: +Or use curl directly. The `-N` flag disables output buffering so you see SSE tokens as they arrive. -> [!NOTE] > `agent_session_id` is optional. If omitted, the server auto-generates one and returns it in the `done` event (`session_id` field). To continue a conversation across turns, pass the same `agent_session_id` in each request. ```bash @@ -141,53 +121,71 @@ curl -sS -N -X POST "http://localhost:8088/invocations?agent_session_id=chat-001 Each response is a stream of SSE events: `token` events with incremental text, followed by a `done` event with the complete reply. -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "What is Microsoft Foundry?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "What is Microsoft Foundry?" -``` +## Option 2: VS Code (Foundry Toolkit) -To stream logs from the running agent: +### Prerequisites -```bash -azd ai agent monitor -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Set the required environment variables (see [Environment variables](#environment-variables)): + + ```bash + export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="" + ``` + +3. Sign in to Azure with the Azure CLI: + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md b/samples/csharp/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md index e842bbf51..25ebd0087 100644 --- a/samples/csharp/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md @@ -27,75 +27,77 @@ This pattern is useful for workflows where an AI agent should **not act autonomo 4. **Poll status** via `GET /invocations/{id}` — useful for checking whether a proposal is still pending after reconnecting. 5. **Cancel** via `POST /invocations/{id}/cancel` — cancels a pending session. -## Running Locally +## Prerequisites -### Prerequisites - -- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) -- Azure CLI installed and authenticated (`az login`) -- An Azure AI Foundry project with a deployed model +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables ```bash export FOUNDRY_PROJECT_ENDPOINT="https://your-resource.openai.azure.com/api/projects/proj" export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" ``` -### Start the Agent +## Option 1: Azure Developer CLI (`azd`) -```bash -dotnet run -``` +### Prerequisites -The agent starts on `http://localhost:8088/`. +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -### Using `azd ai agent run` (Local Development) + ```bash + azd ext install microsoft.foundry + ``` -```bash -azd ai agent run -``` +3. Authenticate: -
-

Using the Foundry Toolkit VS Code Extension

 + ```bash + azd auth login + ``` -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +### Initialize the agent project -Chat with a running agent using the **Agent Inspector**: +No cloning required. Create a new folder and initialize from the manifest: -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +```bash +mkdir human-in-the-loop-agent && cd human-in-the-loop-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/invocations/human-in-the-loop/azure.yaml +``` -
+Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -## Invoke with azd +### Provision Azure resources (if needed) -### Local +If you don't already have a Foundry project and model deployment: -**Bash:** ```bash -azd ai agent invoke --local '{"task": "Write a product launch announcement for Azure AI Foundry"}' +azd provision ``` -**PowerShell:** -```powershell -azd ai agent invoke --local '{\"task\": \"Write a product launch announcement for Azure AI Foundry\"}' +### Run the agent locally + +```bash +azd ai agent run ``` -### Remote (after `azd up`) +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, submit a task: -**Bash:** ```bash -azd ai agent invoke '{"task": "Write a product launch announcement for Azure AI Foundry"}' +azd ai agent invoke --local '{"task": "Write a product launch announcement for Azure AI Foundry"}' ``` -**PowerShell:** +In PowerShell: + ```powershell -azd ai agent invoke '{\"task\": \"Write a product launch announcement for Azure AI Foundry\"}' +azd ai agent invoke --local '{\"task\": \"Write a product launch announcement for Azure AI Foundry\"}' ``` -### Test with curl +This sample uses an approval-gate flow — submit a task, then approve, revise, or reject via curl using the same `agent_session_id`: ```bash # Step 1: Submit a task — agent generates a proposal @@ -131,45 +133,71 @@ curl -X POST http://localhost:8088/invocations//cancel # -> {"status": "cancelled", ...} ``` -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent ```bash azd ai agent invoke '{"task": "Write a product launch announcement for Azure AI Foundry"}' ``` -To stream logs from the running agent: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent monitor -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Set the required environment variables: + + ```bash + export FOUNDRY_PROJECT_ENDPOINT="https://your-resource.openai.azure.com/api/projects/proj" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" + ``` + +3. Sign in to Azure with the Azure CLI: + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Project Structure diff --git a/samples/csharp/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md b/samples/csharp/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md index 51ed1e4a5..e4606de29 100644 --- a/samples/csharp/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md @@ -10,168 +10,142 @@ The agent receives natural language messages via `POST /invocations` and uses Az Notes are stored per session in `notes_{session_id}.jsonl` files, demonstrating **session persistence** — notes survive across multiple invocations within the same session. The session ID is resolved automatically from the `agent_session_id` query parameter. -## Running Locally +## Prerequisites + +1. An existing Foundry project with a deployed model (e.g., `gpt-5.4-mini`), or create them during setup in Option 1. +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. + +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites -- .NET 10.0 SDK -- Azure CLI installed and authenticated (`az login`) -- Foundry project with a deployed model (e.g., `gpt-5.4-mini`) +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -### Using `azd` + ```bash + azd ext install microsoft.foundry + ``` -```bash -azd ai agent run -``` +3. Authenticate: -The agent starts on `http://localhost:8088/`. + ```bash + azd auth login + ``` -
-

Using the Foundry Toolkit VS Code Extension

 +### Initialize the agent project -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +No cloning required. Create a new folder and initialize from the manifest: -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir notetaking-agent && cd notetaking-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/invocations/notetaking-agent/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+### Provision Azure resources (if needed) -### Manual setup +If you don't already have a Foundry project and model deployment: ```bash -dotnet build -cp .env.example .env # then edit values (skip if .env already exists) -export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -dotnet run +azd provision ``` -The agent starts on `http://localhost:8088/`. +### Run the agent locally + +```bash +azd ai agent run +``` -### Test +The agent host will start on `http://localhost:8088`. -#### 1. Test with azd +### Invoke the local agent -**Bash:** ```bash azd ai agent invoke --local '{"message": "save a note - book reservation for dinner"}' ``` -**PowerShell:** +In PowerShell: + ```powershell azd ai agent invoke --local '{\"message\": \"save a note - book reservation for dinner\"}' ``` -#### 2. Test with curl - -##### Save a note +Or use curl directly. Pass a stable `agent_session_id` to persist notes across calls; the `-N` flag streams SSE tokens as they arrive: ```bash curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "save a note - book reservation for dinner"}' -``` -##### Save another note - -```bash curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "save a note - buy groceries"}' -``` -##### Get all notes - -```bash curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "get all my notes"}' -``` -##### Start a new session - -```bash +# Start a new session curl -N -X POST "http://localhost:8088/invocations?agent_session_id=new-session" \ -H "Content-Type: application/json" \ -d '{"message": "get all my notes"}' ``` -#### 3. Test in Agent Inspector +### Deploy to Foundry -Once the agent is running, open **Agent Inspector** in VS Code to interactively send messages and view responses. +Once tested locally, deploy to Microsoft Foundry: -![Agent Inspector](../../../../assets/agent-inspector-invocations.png) - -##### Save a note - -```json -{"message": "save a note - book reservation for dinner"} +```bash +azd deploy ``` -##### Save another note +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent -```json -{"message": "save a note - buy groceries"} +```bash +azd ai agent invoke '{"message": "save a note - book reservation for dinner"}' ``` -##### Get all notes +Stream logs from the running agent with `azd ai agent monitor`. -```json -{"message": "get all my notes"} -``` +## Option 2: VS Code (Foundry Toolkit) -##### Start a new session +### Prerequisites -Click the **Clear Conversation** button at the top-right corner to start a new session. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -## Deploying the Agent to Microsoft Foundry +### Run and debug the agent -Once you've tested locally, deploy to Microsoft Foundry: +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector: -```bash -# Provision Azure resources (skip if already done during local setup) -azd provision +![Agent Inspector](../../../../assets/agent-inspector-invocations.png) -# Build, push, and deploy the agent to Foundry -azd deploy -``` +Try sending `{"message": "save a note - book reservation for dinner"}`, then `{"message": "get all my notes"}`. Click **Clear Conversation** (top-right) to start a new session. -After deploying, invoke the agent running in Foundry: +### Or run manually, then open the Inspector -**Bash:** -```bash -azd ai agent invoke '{"message": "save a note - book reservation for dinner"}' -``` +1. Sign in to Azure with the Azure CLI (`az login`), build, and set env values: -**PowerShell:** -```powershell -azd ai agent invoke '{\"message\": \"save a note - book reservation for dinner\"}' -``` + ```bash + dotnet build + cp .env.example .env # then edit values (skip if .env already exists) + export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" + ``` -To stream logs from the running agent: +2. Start the agent: `dotnet run` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -```bash -azd ai agent monitor -``` +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/bring-your-own/invocations_ws/HelloWorld/README.md b/samples/csharp/hosted-agents/bring-your-own/invocations_ws/HelloWorld/README.md index 3b13a1176..11bbcbe7c 100644 --- a/samples/csharp/hosted-agents/bring-your-own/invocations_ws/HelloWorld/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/invocations_ws/HelloWorld/README.md @@ -65,7 +65,7 @@ shuttle audio bytes and control events. - Verify your version: `dotnet --version` - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) 2. **Azure Developer CLI (`azd`)** (recommended for deploy) - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) and the AI agent extension: `azd ext install azure.ai.agents` + - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) and the Foundry extension: `azd ext install microsoft.foundry` - Authenticated: `azd auth login` 3. **Azure CLI** — installed and authenticated: `az login`. 4. An **Azure AI Services / Voice Live** resource with access to a realtime model (for example `gpt-realtime-1.5`). diff --git a/samples/csharp/hosted-agents/bring-your-own/responses/HelloWorld/README.md b/samples/csharp/hosted-agents/bring-your-own/responses/HelloWorld/README.md index fc9742071..50ec91d7e 100644 --- a/samples/csharp/hosted-agents/bring-your-own/responses/HelloWorld/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/responses/HelloWorld/README.md @@ -30,27 +30,12 @@ The agent is hosted using the [Azure AI AgentServer Responses SDK](https://www.n The hosted agent can be developed and deployed to Microsoft Foundry using the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd). -## Running the Agent Locally +## Prerequisites -### Prerequisites - -Before running this sample, ensure you have: - -1. **Azure Developer CLI (`azd`)** - - [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) and the unified Foundry CLI extension: `azd ext install microsoft.foundry` - - Authenticated: `azd auth login` - -2. **Azure CLI** - - Installed and authenticated: `az login` - -3. **.NET 10.0 SDK or later** - - Verify your version: `dotnet --version` - - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) - -> [!NOTE] -> You do **not** need an existing [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry) project or model deployment to get started — `azd provision` creates them for you. If you already have a project, see the [note below](#using-azd) on how to target it. +1. An existing Foundry project with a deployed model (or create them during setup in Option 1 — `azd provision` can create them for you). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables See [`.env.example`](src/hello-world-dotnet-responses/.env.example) or `.env` for the full list of environment variables this sample uses. @@ -60,72 +45,57 @@ See [`.env.example`](src/hello-world-dotnet-responses/.env.example) or `.env` fo | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name — must match your Foundry project deployment. Declared in `azure.yaml`. | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Recommended | Enables telemetry. Auto-injected in hosted containers; set manually for local dev. | -**Local development (without `azd`):** +When using `azd ai agent run`, these are handled automatically. For manual runs, set them in your shell — .NET does not read `.env` files natively. -```bash -# Set env vars directly — .NET does not natively read .env files -export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="" -``` - -> [!NOTE] -> When using `azd ai agent run`, environment variables are handled automatically — no manual setup needed. +## Option 1: Azure Developer CLI (`azd`) -### Installing Dependencies +### Prerequisites -> [!NOTE] -> If using `azd ai agent run`, dependencies are restored automatically — skip to [Running the Sample](#running-the-sample). +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -Dependencies are restored automatically when building the project: + ```bash + azd ext install microsoft.foundry + ``` -```bash -dotnet restore -``` +3. Authenticate: -### Running the Sample + ```bash + azd auth login + ``` -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. +### Initialize the agent project -
-

Using the Foundry Toolkit VS Code Extension

 +No cloning required. Create a new folder and initialize from the manifest: -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: +```bash +mkdir hello-world-agent && cd hello-world-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/responses/HelloWorld/azure.yaml +``` -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -
+> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. -#### Using [`azd`](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=azd) +### Provision Azure resources (if needed) -No cloning required. Create a new folder, point `azd` at the manifest on GitHub, and it sets up the sample and adopts its `azure.yaml` as the project manifest and configures your environment automatically: +If you don't already have a Foundry project and model deployment: ```bash -# Create a new folder for the agent and navigate into it -mkdir hello-world-agent && cd hello-world-agent - -# Initialize from the manifest — azd reads it, downloads the sample, -# and adopts its azure.yaml as the project manifest and configures your environment -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/dotnet/hosted-agents/bring-your-own/responses/HelloWorld/azure.yaml - -# Provision Azure resources (Foundry project, model deployment, App Insights) azd provision +``` + +### Run the agent locally -# Run the agent locally (handles env vars, build, and startup) +```bash azd ai agent run ``` -> [!NOTE] -> If you've already cloned this repository, pass a local path to the manifest instead: -> `azd ai agent init -m /samples/dotnet/hosted-agents/bring-your-own/responses/HelloWorld/azure.yaml` +The agent host will start on `http://localhost:8088`. -> [!NOTE] -> If you already have a Foundry project and model deployment, add `-p -d ` to `azd ai agent init` to target existing resources. You can also skip provisioning entirely and configure env vars manually — see [Manual setup](#manual-setup). +### Invoke the local agent -The agent starts on `http://localhost:8088/`. To invoke it: +In a separate terminal, invoke the running agent: ```bash azd ai agent invoke --local "What is Microsoft Foundry?" @@ -139,53 +109,71 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "What is Microsoft Foundry?", "stream": false}' | jq . ``` -#### Manual setup +### Deploy to Foundry -If running without `azd`, set environment variables manually (see [Environment Variables](#environment-variables)), then: +Once tested locally, deploy to Microsoft Foundry: ```bash -dotnet run +azd deploy ``` -### Deploying the Agent to Microsoft Foundry +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -Once you've tested locally, deploy to Microsoft Foundry: +### Invoke the deployed agent ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry -azd deploy +azd ai agent invoke "What is Microsoft Foundry?" ``` -After deploying, invoke the agent running in Foundry: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent invoke "What is Microsoft Foundry?" -``` +## Option 2: VS Code (Foundry Toolkit) -To stream logs from the running agent: +### Prerequisites -```bash -azd ai agent monitor -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Set the required environment variables (see [Environment variables](#environment-variables)): + + ```bash + export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="" + ``` + +3. Sign in to Azure with the Azure CLI: + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -#### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/csharp/hosted-agents/bring-your-own/responses/background-agent/README.md b/samples/csharp/hosted-agents/bring-your-own/responses/background-agent/README.md index 7d2faeca4..f12c00d3b 100644 --- a/samples/csharp/hosted-agents/bring-your-own/responses/background-agent/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/responses/background-agent/README.md @@ -10,67 +10,71 @@ The agent receives a request via `POST /responses` with `"background": true`. Th The handler itself stays simple — background mode, polling, and cancellation are all managed by the SDK automatically. -## Running Locally +## Prerequisites -### Prerequisites - -- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) -- Azure CLI installed and authenticated (`az login`) -- An Azure AI Foundry project with an Azure OpenAI deployment +1. An existing Foundry project with an Azure OpenAI model deployment (or create them during setup in Option 1). +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Environment Variables +### Environment variables | Variable | Description | |---|---| | `FOUNDRY_PROJECT_ENDPOINT` | Azure AI Foundry project endpoint (auto-injected when deployed) | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Azure OpenAI model deployment name (e.g., `gpt-5.4-mini`) | -### Using `azd` - -```bash -azd ai agent run -``` +## Option 1: Azure Developer CLI (`azd`) -The agent starts on `http://localhost:8088/`. +### Prerequisites -
-

Using the Foundry Toolkit VS Code Extension

 +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. + ```bash + azd ext install microsoft.foundry + ``` -Chat with a running agent using the **Agent Inspector**: +3. Authenticate: -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. + ```bash + azd auth login + ``` -
+### Initialize the agent project -### Manual setup +No cloning required. Create a new folder and initialize from the manifest: ```bash -export FOUNDRY_PROJECT_ENDPOINT="https://your-resource.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -dotnet run +mkdir background-agent && cd background-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/responses/background-agent/azure.yaml ``` -The agent starts on `http://localhost:8088/`. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -## Invoke with azd +### Provision Azure resources (if needed) -### Local +If you don't already have a Foundry project and model deployment: ```bash -azd ai agent invoke --local "Analyze the impact of AI on healthcare" +azd provision ``` -### Remote (after `azd up`) +### Run the agent locally ```bash -azd ai agent invoke "Analyze the impact of AI on healthcare" +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, invoke the running agent: + +```bash +azd ai agent invoke --local "Analyze the impact of AI on healthcare" ``` -### Test — Background Mode +**Background mode** — submit asynchronously, then poll for the result: ```bash # Submit a background research analysis @@ -85,7 +89,7 @@ curl http://localhost:8088/responses/ curl -X POST http://localhost:8088/responses//cancel ``` -### Test — Default Mode (Synchronous) +**Default (synchronous) mode:** ```bash curl -X POST http://localhost:8088/responses \ @@ -93,45 +97,71 @@ curl -X POST http://localhost:8088/responses \ -d '{"model": "research", "input": "Analyze the impact of AI on healthcare"}' ``` -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) -azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent ```bash azd ai agent invoke "Analyze the impact of AI on healthcare" ``` -To stream logs from the running agent: +Stream logs from the running agent with `azd ai agent monitor`. -```bash -azd ai agent monitor -``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Restore dependencies: + + ```bash + dotnet restore + ``` + +2. Set the required environment variables: + + ```bash + export FOUNDRY_PROJECT_ENDPOINT="https://your-resource.services.ai.azure.com/api/projects/your-project" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" + ``` + +3. Sign in to Azure with the Azure CLI: + + ```bash + az login + ``` + +4. Start the agent (listens on `http://localhost:8088`): + + ```bash + dotnet run + ``` + +5. Open the Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Project Structure diff --git a/samples/csharp/hosted-agents/bring-your-own/responses/env-vars-agent/README.md b/samples/csharp/hosted-agents/bring-your-own/responses/env-vars-agent/README.md index 6bada8187..e49151215 100644 --- a/samples/csharp/hosted-agents/bring-your-own/responses/env-vars-agent/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/responses/env-vars-agent/README.md @@ -47,68 +47,75 @@ Built with [Azure.AI.AgentServer.Responses](https://www.nuget.org/packages/Azure - `get_env_var("SECRET_KEY", "credentials")` → `{ status: "RESOLVED", length: 24, head: "p@ss", … }` *(no raw value)* 5. The model's tool result is fed back for a natural-language reply. -## Running Locally +## Prerequisites + +1. An existing Foundry project with a deployed model (e.g., `gpt-5.4-mini`), or create them during setup in Option 1. +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. +3. **Foundry connections** (for deployment): an **ApiKey** connection `dummy-api-key` and a **CustomKeys** connection `dummy-custom-keys` (with a secret `secret-key` and a plain `plain-key`), as described in [How It Works](#how-it-works). The placeholders in `azure.yaml` resolve against these at container startup. + +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites -- .NET 10.0 SDK -- Azure CLI installed and authenticated (`az login`) -- Foundry project with a deployed model (e.g., `gpt-5.4-mini`) -- (For deployment) the project's hosted-agent feature enabled, plus the two connections referenced above (`dummy-api-key` ApiKey, `dummy-custom-keys` CustomKeys) +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -### Using `azd` + ```bash + azd ext install microsoft.foundry + ``` -```bash -azd ai agent run -``` +3. Authenticate: -The agent starts on `http://localhost:8088/`. + ```bash + azd auth login + ``` + +### Initialize the agent project -### Manual setup +No cloning required. Create a new folder and initialize from the manifest: ```bash -dotnet build -cp .env.example .env # then edit values — fill in any test values you like (skip if .env already exists) -export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -export SECRET_API_KEY="ab12-fake-test-key" -export TARGET="https://api.example.com" -export SECRET_KEY="p@ssw0rd-test-value" -export NON_SECRET_KEY="westus2" -dotnet run +mkdir env-vars-agent && cd env-vars-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/responses/env-vars-agent/azure.yaml ``` -The agent starts on `http://localhost:8088/`. - -### Test +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -#### 1. Test with azd +### Provision Azure resources (if needed) -##### Read the ApiKey target (whole value) +If you don't already have a Foundry project and model deployment: ```bash -azd ai agent invoke --local "what is TARGET? it is the target of an ApiKey connection." +azd provision ``` -##### Read the ApiKey credentials (fingerprint only) +### Run the agent locally ```bash -azd ai agent invoke --local "did SECRET_API_KEY resolve? it is a credentials placeholder." +azd ai agent run ``` -##### Read the CustomKeys metadata (whole value) +The agent host will start on `http://localhost:8088`. -```bash -azd ai agent invoke --local "what is NON_SECRET_KEY? it is metadata from a CustomKeys connection." -``` +### Invoke the local agent -##### Read the CustomKeys credentials (fingerprint only) +Ask the agent about each env var. The tool returns whole values for `target`/`metadata` and a safe fingerprint for `credentials`: ```bash +# ApiKey target (whole value) +azd ai agent invoke --local "what is TARGET? it is the target of an ApiKey connection." + +# ApiKey credentials (fingerprint only) +azd ai agent invoke --local "did SECRET_API_KEY resolve? it is a credentials placeholder." + +# CustomKeys metadata (whole value) +azd ai agent invoke --local "what is NON_SECRET_KEY? it is metadata from a CustomKeys connection." + +# CustomKeys credentials (fingerprint only) azd ai agent invoke --local "did SECRET_KEY resolve? it is a credentials placeholder." ``` -#### 2. Test with curl +Or use curl directly: ```bash curl -X POST http://localhost:8088/responses \ @@ -122,43 +129,65 @@ curl -X POST http://localhost:8088/responses \ --no-buffer ``` -#### 3. Test in Agent Inspector +### Deploy to Foundry -Once the agent is running, open **Agent Inspector** in VS Code to interactively send messages and view responses. +Once tested locally, deploy to Microsoft Foundry: -``` -what is TARGET? it is the target of an ApiKey connection. +```bash +azd deploy ``` -``` -did SECRET_KEY resolve? it is a credentials placeholder. +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "did SECRET_API_KEY resolve? it is a credentials placeholder." ``` -## Deploying the Agent to Microsoft Foundry +Stream logs from the running agent with `azd ai agent monitor`. -Once you've tested locally, deploy to Microsoft Foundry: +## Option 2: VS Code (Foundry Toolkit) -```bash -# Provision Azure resources (skip if already done during local setup) -azd provision +### Prerequisites -# Build, push, and deploy the agent to Foundry -azd deploy -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -After deploying, invoke the agent running in Foundry: +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Try a message such as: -```bash -azd ai agent invoke "did SECRET_API_KEY resolve? it is a credentials placeholder." +``` +what is TARGET? it is the target of an ApiKey connection. ``` -To stream logs from the running agent: +### Or run manually, then open the Inspector -```bash -azd ai agent monitor -``` +1. Sign in to Azure with the Azure CLI (`az login`), build, and set test env values: + + ```bash + dotnet build + cp .env.example .env # then edit values — fill in any test values you like (skip if .env already exists) + export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" + export SECRET_API_KEY="ab12-fake-test-key" + export TARGET="https://api.example.com" + export SECRET_KEY="p@ssw0rd-test-value" + export NON_SECRET_KEY="westus2" + ``` + +2. Start the agent: `dotnet run` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## How the Connection Resolution Works diff --git a/samples/csharp/hosted-agents/bring-your-own/responses/notetaking-agent/README.md b/samples/csharp/hosted-agents/bring-your-own/responses/notetaking-agent/README.md index 96e120ac8..0cedeced2 100644 --- a/samples/csharp/hosted-agents/bring-your-own/responses/notetaking-agent/README.md +++ b/samples/csharp/hosted-agents/bring-your-own/responses/notetaking-agent/README.md @@ -10,160 +10,142 @@ The agent receives natural language messages via `POST /responses` and uses Azur Notes are stored per session in `notes_{session_id}.jsonl` files, demonstrating **session persistence** — notes survive across multiple invocations within the same session. -## Running Locally +## Prerequisites -### Prerequisites - -- .NET 10.0 SDK -- Azure CLI installed and authenticated (`az login`) -- Foundry project with a deployed model (e.g., `gpt-5.4-mini`) +1. An existing Foundry project with a deployed model (e.g., `gpt-5.4-mini`), or create them during setup in Option 1. +2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later. -### Using `azd` +## Option 1: Azure Developer CLI (`azd`) -```bash -azd ai agent run -``` - -The agent starts on `http://localhost:8088/`. +### Prerequisites -
-

Using the Foundry Toolkit VS Code Extension

 +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. + ```bash + azd ext install microsoft.foundry + ``` -Chat with a running agent using the **Agent Inspector**: +3. Authenticate: -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. + ```bash + azd auth login + ``` -
+### Initialize the agent project -### Manual setup +No cloning required. Create a new folder and initialize from the manifest: ```bash -dotnet build -cp .env.example .env # then edit values (skip if .env already exists) -export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -dotnet run +mkdir notetaking-agent && cd notetaking-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/csharp/hosted-agents/bring-your-own/responses/notetaking-agent/azure.yaml ``` -The agent starts on `http://localhost:8088/`. +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. -### Test +### Provision Azure resources (if needed) -#### 1. Test with azd - -> **Note:** Run all `azd` commands from this sample directory (where `azure.yaml` is located) so that session state is persisted across calls. - -##### Save a note +If you don't already have a Foundry project and model deployment: ```bash -azd ai agent invoke --local "save a note - book reservation for dinner" +azd provision ``` -##### Save another note +### Run the agent locally ```bash -azd ai agent invoke --local "save a note - buy groceries" +azd ai agent run ``` -##### Get all notes +The agent host will start on `http://localhost:8088`. -```bash -azd ai agent invoke --local "get all my notes" -``` +### Invoke the local agent -##### Start a new session +> Run `azd` commands from the project directory (where `azure.yaml` is) so session state persists across calls. ```bash +azd ai agent invoke --local "save a note - book reservation for dinner" +azd ai agent invoke --local "save a note - buy groceries" +azd ai agent invoke --local "get all my notes" + +# Start a new session azd ai agent invoke --local --new-session --new-conversation "get all my notes" ``` -#### 2. Test with curl - -##### Save a note +Or use curl directly (pass a stable `agent_session_id` to persist notes across calls): ```bash curl -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ -d '{"input": "save a note - book reservation for dinner", "agent_session_id": "my-session"}' \ --no-buffer -``` - -##### Get all notes -```bash curl -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ -d '{"input": "get all my notes", "agent_session_id": "my-session"}' \ --no-buffer ``` -#### 3. Test in Agent Inspector +### Deploy to Foundry -Once the agent is running, open **Agent Inspector** in VS Code to interactively send messages and view responses. +Once tested locally, deploy to Microsoft Foundry: -![Agent Inspector](../../../../assets/agent-inspector-responses.png) +```bash +azd deploy +``` -##### Save a note +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -``` -save a note - book reservation for dinner +### Invoke the deployed agent + +```bash +azd ai agent invoke "save a note - book reservation for dinner" ``` -##### Save another note +Stream logs from the running agent with `azd ai agent monitor`. -``` -save a note - buy groceries -``` +## Option 2: VS Code (Foundry Toolkit) -##### Get all notes +### Prerequisites -``` -get all my notes -``` +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. +3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready. -## Deploying the Agent to Microsoft Foundry +### Run and debug the agent -Once you've tested locally, deploy to Microsoft Foundry: +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector: -```bash -# Provision Azure resources (skip if already done during local setup) -azd provision +![Agent Inspector](../../../../assets/agent-inspector-responses.png) -# Build, push, and deploy the agent to Foundry -azd deploy +Try: + +``` +save a note - book reservation for dinner +save a note - buy groceries +get all my notes ``` -After deploying, invoke the agent running in Foundry: +### Or run manually, then open the Inspector -```bash -azd ai agent invoke "save a note - book reservation for dinner" -``` +1. Sign in to Azure with the Azure CLI (`az login`), build, and set env values: -To stream logs from the running agent: + ```bash + dotnet build + cp .env.example .env # then edit values (skip if .env already exists) + export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" + export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" + ``` -```bash -azd ai agent monitor -``` +2. Start the agent: `dotnet run` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). - -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/AGENTS.md b/samples/python/hosted-agents/AGENTS.md new file mode 100644 index 000000000..cb2d34a22 --- /dev/null +++ b/samples/python/hosted-agents/AGENTS.md @@ -0,0 +1,51 @@ +# Coding Agent Instructions — Python hosted-agent samples + +Conventions for AI agents creating or editing samples under +`samples/python/hosted-agents/`. Agents read the nearest `AGENTS.md` up the +tree, so this applies to Python hosted-agent samples. Treat these as shared +conventions and a starting point — adapt to what each sample actually needs. + +## README conventions + +Most samples follow the shared template, +[`README-template.md`](./README-template.md): a good default is to copy it and +fill in the `{{placeholders}}`. It keeps a familiar section flow: + +1. What this sample demonstrates +2. How it works — plus any sample-specific background (e.g. "Environment + variables", "Architecture", "Features") +3. Prerequisites — what the *sample* needs: a Foundry project + model deployment, + **Python 3.10+**, and (only if applicable) RBAC roles, extra Azure resources, + and environment variables / secrets +4. Option 1: Azure Developer CLI (`azd`) — init → provision → run → invoke → + deploy → invoke-deployed +5. Option 2: VS Code (Foundry Toolkit) — the one-click **F5** run-and-debug flow + (Agent Inspector opens automatically) and/or a manual run (`python main.py`) + → open the Agent Inspector → deploy +6. Any sample-specific deep-dive sections (customization, advanced demos, reference) +7. Troubleshooting +8. Next steps + +## Conventions worth keeping + +- Prefer the current CLI commands (the template reflects these; avoid older + forms such as `azd ext install azure.ai.agents`). +- Prefer self-contained READMEs over deferring run/deploy steps to a parent + README or hiding steps inside collapsible `
` blocks. + +## When a sample legitimately differs + +Not every sample fits the two-option shape, and that's fine — adapt rather than +force it: + +- **Command-line-only samples** (e.g. VoiceLive, WebSocket, some A2A samples) may + have no VS Code / Agent Inspector path. Document the flow they actually support + (curl / `azd` / a browser client) and omit Option 2 when it doesn't apply. +- **Deploy-first samples** (e.g. A2A) may lead with deployment instead of a local + run. Keep the section order sensible for the scenario. + +Use the template for structure and shared vocabulary, and keep whatever +sample-specific sections a reader needs. + +> The per-sample `AGENTS.md` (hosted-agent overview, `azd` lifecycle, Microsoft +> Foundry Skill) still applies; this file only adds README conventions. diff --git a/samples/python/hosted-agents/README-template.md b/samples/python/hosted-agents/README-template.md new file mode 100644 index 000000000..ba3a8c0fe --- /dev/null +++ b/samples/python/hosted-agents/README-template.md @@ -0,0 +1,164 @@ + + +# What this sample demonstrates + +{{One or two sentences: what the agent does and which framework it uses.}} + +## How it works + +{{Short description of how the agent is wired.}} See `main.py` for the implementation. + + + +## Prerequisites + +What the **sample itself** needs, independent of how you run it. The tooling for each run +path (`azd` or the VS Code Foundry Toolkit) is listed under its option below. + +1. An existing Foundry project with a deployed model (or create them during setup in Option 1). +2. **Python 3.10 or later.** +3. **Roles (RBAC):** {{Azure roles the identity running the sample needs on the Foundry project or other resources, e.g. `Azure AI User`. Delete if project access is sufficient.}} +4. **Additional Azure resources:** {{Extra resources the sample depends on — a toolbox, connection, storage account, etc. If declared in the sample's `azure.yaml`, `azd provision` (Option 1) creates them; otherwise create them before running (Foundry portal, SDK, or `azd ai`). Delete if none.}} +5. **Environment variables / secrets:** {{Required env vars or secrets, e.g. `GITHUB_PAT`, and how to obtain them. Delete if none.}} + +## Option 1: Azure Developer CLI (`azd`) + +### Prerequisites + +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir my-agent && cd my-agent +azd ai agent init -m {{URL to your sample's azure.yaml on GitHub}} +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, from the project directory: + +```bash +azd ai agent invoke --local "{{prompt}}" +``` + +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "{{prompt}}" +``` + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + + + +## Troubleshooting + +> Delete if not needed. List errors specific to this sample and their fixes. + +{{Symptom → cause → fix.}} + +## Next steps + +- [Quickstart: Create a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent) +- {{Links to related samples.}} diff --git a/samples/python/hosted-agents/agent-framework/README.md b/samples/python/hosted-agents/agent-framework/README.md index 96f093827..7416fea03 100644 --- a/samples/python/hosted-agents/agent-framework/README.md +++ b/samples/python/hosted-agents/agent-framework/README.md @@ -148,15 +148,24 @@ The extension also adds an **Agent Inspector** UI for chatting with a hosted age #### Prerequisites 1. **Foundry Toolkit VS Code Extension** — [install from the VS Code marketplace](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=vscode) and sign in to Azure. -2. The agent is already running locally — start it with [`azd ai agent run`](#using-azd) or [`python main.py`](#using-python) first. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -#### Open the Agent Inspector +#### Set up the Python virtual environment -With the agent running on `http://localhost:8088/`: +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** (or **Python: Select Interpreter** to use an existing one). +- Install dependencies: `pip install uv && uv pip install -r requirements.txt` + +#### Run and debug with F5 (recommended) + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. + +#### Or run manually, then open the Inspector + +Once the agent is running on `http://localhost:8088/` (via [`azd ai agent run`](#using-azd) or [`python main.py`](#using-python)): 1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. 2. The Inspector auto-connects to the running agent. -3. Send messages from the Inspector to chat with the agent and watch the streamed responses. +3. Send messages to chat and watch the streamed responses.
diff --git a/samples/python/hosted-agents/agent-framework/invocations/01-basic/README.md b/samples/python/hosted-agents/agent-framework/invocations/01-basic/README.md index e8d934775..7fbb8fb04 100644 --- a/samples/python/hosted-agents/agent-framework/invocations/01-basic/README.md +++ b/samples/python/hosted-agents/agent-framework/invocations/01-basic/README.md @@ -90,23 +90,32 @@ azd ai agent invoke '{"message": "Hi"}' ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/01-basic/README.md b/samples/python/hosted-agents/agent-framework/responses/01-basic/README.md index 3095f6b52..a80b17e18 100644 --- a/samples/python/hosted-agents/agent-framework/responses/01-basic/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/01-basic/README.md @@ -76,23 +76,32 @@ azd ai agent invoke "Hi" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/02-tools/README.md b/samples/python/hosted-agents/agent-framework/responses/02-tools/README.md index 9e1a7e5ef..ec2eb65e3 100644 --- a/samples/python/hosted-agents/agent-framework/responses/02-tools/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/02-tools/README.md @@ -76,23 +76,32 @@ azd ai agent invoke "What is the weather in Seattle?" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/03-mcp/README.md b/samples/python/hosted-agents/agent-framework/responses/03-mcp/README.md index b9e642ba8..ebb5bc2cd 100644 --- a/samples/python/hosted-agents/agent-framework/responses/03-mcp/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/03-mcp/README.md @@ -85,23 +85,32 @@ azd ai agent invoke "List all the repositories I own on GitHub." ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/README.md b/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/README.md index 9e9dce416..b32f4be63 100644 --- a/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/README.md @@ -194,24 +194,28 @@ azd ai agent invoke "What tools do you have?" #### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://learn.microsoft.com/en-us/azure/foundry/how-to/develop/get-started-projects-vs-code)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. 3. The `agent-tools` toolbox must exist in your Foundry project. Create it from the bundled [`toolbox.yaml`](src/agent-framework-agent-with-foundry-toolbox-responses/toolbox.yaml) (`azd ai toolbox create agent-tools --from-file ./toolbox.yaml`) or in the Foundry portal before you run the agent. -#### Create the project +#### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + ```bash + pip install uv + uv pip install -r requirements.txt + ``` #### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -#### Test with Agent Inspector +#### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. #### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/05-workflows/README.md b/samples/python/hosted-agents/agent-framework/responses/05-workflows/README.md index 6937e370f..81876f551 100644 --- a/samples/python/hosted-agents/agent-framework/responses/05-workflows/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/05-workflows/README.md @@ -80,23 +80,32 @@ azd ai agent invoke "Create a slogan for a new electric SUV that is affordable a ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/06-files/README.md b/samples/python/hosted-agents/agent-framework/responses/06-files/README.md index 3e83b2e6d..6ea77c0fe 100644 --- a/samples/python/hosted-agents/agent-framework/responses/06-files/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/06-files/README.md @@ -105,23 +105,32 @@ azd ai agent invoke --new-session "Hi!" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/07-skills/README.md b/samples/python/hosted-agents/agent-framework/responses/07-skills/README.md index 6df7d4d01..9f44bef0a 100644 --- a/samples/python/hosted-agents/agent-framework/responses/07-skills/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/07-skills/README.md @@ -101,23 +101,32 @@ azd ai agent invoke "Create a colorful 3-day PDF travel guide for Lisbon focused ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/08-observability/README.md b/samples/python/hosted-agents/agent-framework/responses/08-observability/README.md index 6915ffb87..66bf57ca8 100644 --- a/samples/python/hosted-agents/agent-framework/responses/08-observability/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/08-observability/README.md @@ -100,23 +100,32 @@ azd ai agent invoke "Hi" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/09-declarative-customer-support/README.md b/samples/python/hosted-agents/agent-framework/responses/09-declarative-customer-support/README.md index edcdabfe6..79f1efa93 100644 --- a/samples/python/hosted-agents/agent-framework/responses/09-declarative-customer-support/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/09-declarative-customer-support/README.md @@ -120,23 +120,32 @@ azd ai agent invoke "I have a problem" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/10-downstream-azure/README.md b/samples/python/hosted-agents/agent-framework/responses/10-downstream-azure/README.md index 6d85346c7..ddf2be912 100644 --- a/samples/python/hosted-agents/agent-framework/responses/10-downstream-azure/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/10-downstream-azure/README.md @@ -176,11 +176,38 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" (Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Read the blob hello.txt and tell me what it contains."}').Content ``` -### Test in Agent Inspector +### Test in VS Code (Foundry Toolkit) -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +**Prerequisites** -Type the following message in Inspector: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**. + +Type the following in the Inspector: ``` Read the blob hello.txt and tell me what it contains. diff --git a/samples/python/hosted-agents/agent-framework/responses/11-azure-search-rag/README.md b/samples/python/hosted-agents/agent-framework/responses/11-azure-search-rag/README.md index 5c6c67627..71fbc59af 100644 --- a/samples/python/hosted-agents/agent-framework/responses/11-azure-search-rag/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/11-azure-search-rag/README.md @@ -204,23 +204,32 @@ azd ai agent invoke "What is your return policy?" ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills/README.md b/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills/README.md index dd53bd203..9f645bf87 100644 --- a/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills/README.md @@ -120,6 +120,37 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" Because skills are loaded on demand, the canary token in a response also proves the model actually invoked `load_skill` for the matching skill (not just saw its name in the advertised list). +### Test in VS Code (Foundry Toolkit) + +**Prerequisites** + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + ## Deploying the Agent to Foundry To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](../../README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. diff --git a/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/README.md b/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/README.md index 21264ccfa..8b43f666d 100644 --- a/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/README.md @@ -168,23 +168,32 @@ Created memory store 'agent_framework_memory' (id=memstore_...). ### Prerequisites -1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed. -2. Sign in to Azure in VS Code. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -### Create the project +### Set up the Python virtual environment -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` ### Run and debug the agent -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Test with Agent Inspector +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ### Deploy to Foundry diff --git a/samples/python/hosted-agents/agent-framework/responses/14-browser-automation-agent/README.md b/samples/python/hosted-agents/agent-framework/responses/14-browser-automation-agent/README.md index b63833d90..57f46154e 100644 --- a/samples/python/hosted-agents/agent-framework/responses/14-browser-automation-agent/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/14-browser-automation-agent/README.md @@ -148,13 +148,40 @@ curl -X POST http://localhost:8088/responses \ -d '{"input": "Now take a screenshot of the page.", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}' ``` -### Test in Agent Inspector +### Test in VS Code (Foundry Toolkit) -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +**Prerequisites** -Type the following message in Inspector: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -```text +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**. + +Type the following in the Inspector: + +``` Open https://example.com and report the page title. ``` diff --git a/samples/python/hosted-agents/agent-framework/responses/15-optimization-travel-approver/README.md b/samples/python/hosted-agents/agent-framework/responses/15-optimization-travel-approver/README.md index 5af09b138..cbcb7bf4d 100644 --- a/samples/python/hosted-agents/agent-framework/responses/15-optimization-travel-approver/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/15-optimization-travel-approver/README.md @@ -104,12 +104,40 @@ azd deploy azd ai agent invoke "I need to book a trip to Tokyo next week for a client meeting. Budget is $5000." ``` -## Option 2: Foundry Toolkit VS Code Extension +## Option 2: VS Code (Foundry Toolkit) -1. Clone this repo and open this sample folder in VS Code. -2. Start locally: `azd ai agent run` -3. Open Command Palette → **Foundry Toolkit: Open Agent Inspector** to chat. -4. When ready: **Foundry Toolkit: Deploy Hosted Agent**. +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +Run **Foundry Toolkit: Deploy Hosted Agent** and follow the wizard. ## Running Optimization diff --git a/samples/python/hosted-agents/agent-framework/responses/16-content-safety-guardrail/README.md b/samples/python/hosted-agents/agent-framework/responses/16-content-safety-guardrail/README.md index 02ccd61c9..1aa5853f5 100644 --- a/samples/python/hosted-agents/agent-framework/responses/16-content-safety-guardrail/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/16-content-safety-guardrail/README.md @@ -77,10 +77,39 @@ azd ai agent invoke "Write a short friendly hello message." ## Option 2: VS Code (Foundry Toolkit) -1. Install the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension and sign in to Azure. -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**, then select this sample from the gallery. The extension scaffolds the project and generates `agent.yaml`. -1. Set `rai_policy_name` in the generated `azure.yaml` to your policy's full ARM resource ID. -1. Run **Foundry Toolkit: Deploy Hosted Agent** and follow the wizard to deploy. +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Set `rai_policy_name` in `azure.yaml` to your policy's full ARM resource ID. +2. Run **Foundry Toolkit: Deploy Hosted Agent** and follow the wizard to deploy. ## Verify the guardrail diff --git a/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/README.md b/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/README.md index 33ff19564..9a0c757b9 100644 --- a/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/README.md +++ b/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/README.md @@ -172,14 +172,13 @@ azd ai toolbox create knowledge-base --from-file ./toolbox.yaml azd env set TOOLBOX_ENDPOINT "https://.services.ai.azure.com/api/projects//toolboxes/knowledge-base/mcp?api-version=v1" ``` -### Option 2: VS Code (Foundry Toolkit) +## Option 2: VS Code (Foundry Toolkit) > The VS Code flow doesn't run the `azd` hook — provision the knowledge base, connection, and toolbox first with [Provision manually](#provision-manually-without-the-hook). -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**, then select this sample. -2. Press **F5** to run and debug the agent locally on `http://localhost:8088`. -3. Run **Foundry Toolkit: Open Agent Inspector** to chat with the running agent. -4. Run **Foundry Toolkit: Deploy Hosted Agent** to build the image, register the version, and assign RBAC. +1. Open the sample folder in VS Code (after `azd ai agent init` from Option 1). +2. Press **F5** to run and debug the agent. The **Agent Inspector** opens automatically — chat with the agent in the Inspector. +3. Run **Foundry Toolkit: Deploy Hosted Agent** to build the image, register the version, and assign RBAC. ## Try it diff --git a/samples/python/hosted-agents/bring-your-own/invocations/ag-ui/README.md b/samples/python/hosted-agents/bring-your-own/invocations/ag-ui/README.md index 43c7fb281..4be4d4f6b 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/ag-ui/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/ag-ui/README.md @@ -20,14 +20,14 @@ A minimal getting-started agent implementing the [AG-UI protocol](https://docs.a > **Note:** Authentication uses `DefaultAzureCredential` (managed identity, Azure CLI, etc.) — no API key needed. -## Running Locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites - Python 3.10+ - A Foundry project with a deployed model -### Using `azd` +### Run the agent locally ```bash azd ai agent run @@ -35,32 +35,9 @@ azd ai agent run The agent starts on `http://localhost:8088/`. -
-

Using the Foundry Toolkit VS Code Extension

 +### Invoke the local agent -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # then fill in values (skip if .env already exists) -python main.py -``` - -The agent starts on `http://localhost:8088/`. - -## Invoke with azd - -### Local +In a separate terminal, invoke the running agent: **Bash:** ```bash @@ -72,19 +49,7 @@ azd ai agent invoke --local '{"threadId": "thread-1", "runId": "run-1", "state": azd ai agent invoke --local '{\"threadId\": \"thread-1\", \"runId\": \"run-1\", \"state\": {}, \"messages\": [{\"id\": \"msg-1\", \"role\": \"user\", \"content\": \"Hello\"}], \"tools\": [], \"context\": [], \"forwardedProps\": {}}' ``` -### Remote (after `azd up`) - -**Bash:** -```bash -azd ai agent invoke '{"threadId": "thread-1", "runId": "run-1", "state": {}, "messages": [{"id": "msg-1", "role": "user", "content": "Hello"}], "tools": [], "context": [], "forwardedProps": {}}' -``` - -**PowerShell:** -```powershell -azd ai agent invoke '{\"threadId\": \"thread-1\", \"runId\": \"run-1\", \"state\": {}, \"messages\": [{\"id\": \"msg-1\", \"role\": \"user\", \"content\": \"Hello\"}], \"tools\": [], \"context\": [], \"forwardedProps\": {}}' -``` - -### Test with curl +Or invoke directly with curl: ```bash curl -N -X POST http://localhost:8088/invocations \ @@ -101,22 +66,9 @@ curl -N -X POST http://localhost:8088/invocations \ }' ``` -### SSE Event Format - -Standard AG-UI events are streamed automatically: - -``` -data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"} -data: {"type":"TEXT_MESSAGE_START","messageId":"...","role":"assistant"} -data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"Hello"} -data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"! How"} -data: {"type":"TEXT_MESSAGE_END","messageId":"..."} -data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"} -``` - -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash # Provision Azure resources (skip if already done during local setup) @@ -126,7 +78,9 @@ azd provision azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent ```bash azd ai agent invoke '{"threadId": "thread-1", "runId": "run-1", "state": {}, "messages": [{"id": "msg-1", "role": "user", "content": "Hello"}], "tools": [], "context": [], "forwardedProps": {}}' @@ -138,23 +92,58 @@ To stream logs from the running agent: azd ai agent monitor ``` -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. +## SSE Event Format + +Standard AG-UI events are streamed automatically: + +``` +data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"} +data: {"type":"TEXT_MESSAGE_START","messageId":"...","role":"assistant"} +data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"Hello"} +data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"! How"} +data: {"type":"TEXT_MESSAGE_END","messageId":"..."} +data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"} +``` + ## Learn More - [AG-UI Protocol](https://docs.ag-ui.com/introduction) — event types, lifecycle, tools diff --git a/samples/python/hosted-agents/bring-your-own/invocations/claude-agent-sdk/README.md b/samples/python/hosted-agents/bring-your-own/invocations/claude-agent-sdk/README.md index dbb1283d6..85be45c14 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/claude-agent-sdk/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/claude-agent-sdk/README.md @@ -22,7 +22,7 @@ This sample is configured for **Microsoft Foundry** mode by default | `ANTHROPIC_MODEL` | Built-in default | Explicit startup model set to `claude-opus-4-7` | | `ANTHROPIC_FOUNDRY_BASE_URL` | Auto-generated | Automatically constructed from `FOUNDRY_PROJECT_ENDPOINT` as `https://.services.ai.azure.com/anthropic` | -## Running Locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites @@ -30,45 +30,21 @@ This sample is configured for **Microsoft Foundry** mode by default - `az login` - A Foundry resource with Claude model deployments -### Using `azd` +### Run the agent locally ```bash - azd ai agent run ``` This sample sets `ANTHROPIC_MODEL=claude-opus-4-7` in YAML, you can change the model here. -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # skip if .env already exists -python main.py -``` - -## Invoke - -### Local +### Invoke the local agent ```bash azd ai agent invoke --local "Hey hi" ``` -### Curl +Or invoke directly with curl: ```bash curl -sS -N -X POST http://localhost:8088/invocations \ @@ -76,26 +52,52 @@ curl -sS -N -X POST http://localhost:8088/invocations \ -d "List the main Python files in this folder." ``` -## Deploying to Microsoft Foundry +### Deploy to Foundry ```bash azd provision azd deploy ``` -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +> After deployment, configure RBAC — see [⚠️ CRITICAL: RBAC Configuration After Deployment](#-critical-rbac-configuration-after-deployment) below. + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## ⚠️ CRITICAL: RBAC Configuration After Deployment diff --git a/samples/python/hosted-agents/bring-your-own/invocations/github-copilot/README.md b/samples/python/hosted-agents/bring-your-own/invocations/github-copilot/README.md index 4a3ea6b32..7a8f9bd89 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/github-copilot/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/github-copilot/README.md @@ -29,18 +29,33 @@ This agent supports two LLM backends. Configure one of the following: - If only `GITHUB_TOKEN` is set → uses the **GitHub Copilot model** (quickest way to get started) - If both are set → the **Foundry model takes precedence** -## Running Locally +## Prerequisites + +- **Python 3.10+** +- A GitHub fine-grained PAT (`github_pat_` prefix) + + Create one at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new) with **Account permissions → Copilot Requests → Read-only**. + + > **Note:** Classic tokens (`ghp_`) are not supported. Use a fine-grained PAT (`github_pat_`), OAuth token (`gho_`), or GitHub App user token (`ghu_`). + +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites -- Python 3.10+ -- A GitHub fine-grained PAT (`github_pat_` prefix) +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -Create one at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new) with **Account permissions → Copilot Requests → Read-only**. + ```bash + azd ext install microsoft.foundry + ``` -> **Note:** Classic tokens (`ghp_`) are not supported. Use a fine-grained PAT (`github_pat_`), OAuth token (`gho_`), or GitHub App user token (`ghu_`). +3. Authenticate: -### Using `azd` + ```bash + azd auth login + ``` + +### Set up the GitHub token Create a local `.env` file from the sample template and set `GITHUB_TOKEN`: @@ -55,7 +70,7 @@ The sample loads `.env` automatically when running locally. If you plan to deplo azd env set GITHUB_TOKEN="github_pat_..." ``` -Next, start the agent locally with the `run` command: +### Run the agent locally ```bash azd ai agent run @@ -63,33 +78,7 @@ azd ai agent run The agent starts on `http://localhost:8088/`. -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # skip if .env already exists -# Edit .env and set GITHUB_TOKEN=github_pat_... -python main.py -``` - -The agent starts on `http://localhost:8088/`. - -## Invoke with azd - -### Local +### Invoke the local agent **Bash:** ```bash @@ -101,7 +90,7 @@ azd ai agent invoke --local '{"input": "What can you help me with?"}' azd ai agent invoke --local '{\"input\": \"What can you help me with?\"}' ``` -### Test with curl +Or invoke directly with curl: ```bash # First message @@ -115,33 +104,9 @@ curl -N -X POST http://localhost:8088/invocations \ -d '{"input": "Give me a code example"}' ``` -### SSE Event Format - -Each Copilot SDK event is streamed via `event.to_dict()`: - -``` -data: {"type": "assistant.message_delta", "data": {"delta_content": "Python is"}}\n\n -data: {"type": "assistant.message_delta", "data": {"delta_content": " a programming"}}\n\n -... -event: done -data: {"invocation_id": "...", "session_id": "..."} -``` - -## Using Your Own Foundry Model - -To use your own Azure AI Foundry model instead of the Copilot model, set the Foundry variables (no `GITHUB_TOKEN` needed): - -```bash -FOUNDRY_PROJECT_ENDPOINT=https://.services.ai.azure.com/api/projects/ \ -AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o \ -python main.py -``` - -Authentication uses Managed Identity via `DefaultAzureCredential`. When deployed as a hosted agent, `FOUNDRY_PROJECT_ENDPOINT` is auto-injected by the platform — you only need to set `AZURE_AI_MODEL_DEPLOYMENT_NAME` in `azure.yaml`. - -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash # Provision Azure resources (skip if already done during local setup) @@ -151,7 +116,9 @@ azd provision azd deploy ``` -After deploying, invoke the agent running in Foundry: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent **Bash:** ```bash @@ -169,9 +136,38 @@ To stream logs from the running agent: azd ai agent monitor ``` -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment -### Deploying with the Foundry Toolkit VS Code Extension +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry 1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. 2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. @@ -186,6 +182,30 @@ For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka. - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. +## SSE Event Format + +Each Copilot SDK event is streamed via `event.to_dict()`: + +``` +data: {"type": "assistant.message_delta", "data": {"delta_content": "Python is"}}\n\n +data: {"type": "assistant.message_delta", "data": {"delta_content": " a programming"}}\n\n +... +event: done +data: {"invocation_id": "...", "session_id": "..."} +``` + +## Using Your Own Foundry Model + +To use your own Azure AI Foundry model instead of the Copilot model, set the Foundry variables (no `GITHUB_TOKEN` needed): + +```bash +FOUNDRY_PROJECT_ENDPOINT=https://.services.ai.azure.com/api/projects/ \ +AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o \ +python main.py +``` + +Authentication uses Managed Identity via `DefaultAzureCredential`. When deployed as a hosted agent, `FOUNDRY_PROJECT_ENDPOINT` is auto-injected by the platform — you only need to set `AZURE_AI_MODEL_DEPLOYMENT_NAME` in `azure.yaml`. + ## Adding Skills Any subdirectory under `skills/` containing a `SKILL.md` file is automatically loaded by the Copilot SDK. The included `joke` skill demonstrates this: diff --git a/samples/python/hosted-agents/bring-your-own/invocations/hello-world/README.md b/samples/python/hosted-agents/bring-your-own/invocations/hello-world/README.md index b9e40554e..4cb4d8989 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/hello-world/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/hello-world/README.md @@ -90,13 +90,34 @@ Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the F

Using the Foundry Toolkit VS Code Extension

 -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +**Prerequisites** -Chat with a running agent using the **Agent Inspector**: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test.
diff --git a/samples/python/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md b/samples/python/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md index 6ac63d0e7..14d937a0e 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/human-in-the-loop/README.md @@ -34,7 +34,7 @@ The agent includes an inline OpenAPI 3.0 specification that documents the reques GET http://localhost:8088/invocations/docs/openapi.json ``` -## Running Locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites @@ -42,7 +42,7 @@ GET http://localhost:8088/invocations/docs/openapi.json - Azure CLI installed and authenticated (`az login`) - Azure OpenAI resource with a deployed model -### Using `azd` +### Run the agent locally ```bash azd ai agent run @@ -50,58 +50,14 @@ azd ai agent run The agent starts on `http://localhost:8088/`. -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # then edit values (skip if .env already exists) -export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -python main.py -``` - -The agent starts on `http://localhost:8088/`. - -## Invoke with azd - -### Local +### Invoke the local agent **Bash:** ```bash azd ai agent invoke --local '{"task": "Write a product launch announcement for Azure AI Foundry"}' ``` -**PowerShell:** -```powershell -azd ai agent invoke --local '{\"task\": \"Write a product launch announcement for Azure AI Foundry\"}' -``` - -### Remote (after `azd up`) - -**Bash:** -```bash -azd ai agent invoke '{"task": "Write a product launch announcement for Azure AI Foundry"}' -``` - -**PowerShell:** -```powershell -azd ai agent invoke '{\"task\": \"Write a product launch announcement for Azure AI Foundry\"}' -``` - -### Test with curl +Or drive the full multi-step approval flow with curl: ```bash # Fetch the OpenAPI spec @@ -140,19 +96,16 @@ curl -X POST http://localhost:8088/invocations//cancel # -> {"status": "cancelled", ...} ``` -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke '{"task": "Write a product launch announcement for Azure AI Foundry"}' @@ -166,19 +119,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/bring-your-own/invocations/langgraph-chat/README.md b/samples/python/hosted-agents/bring-your-own/invocations/langgraph-chat/README.md index 8ddffe8a2..049a7c4de 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/langgraph-chat/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/langgraph-chat/README.md @@ -39,48 +39,21 @@ and Azure OpenAI, hosted via the **invocations** protocol. | `FOUNDRY_PROJECT_ENDPOINT` | Yes | — | Foundry project endpoint URL | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | — | Model deployment name declared in `azure.yaml` | -## Running locally +## Option 1: Azure Developer CLI (`azd`) -### Using `azd` +### Run the agent locally ```bash azd ai agent run ``` -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup +### Invoke the local agent -```bash -cp .env.example .env # then edit values (skip if .env already exists) -pip install -r requirements.txt -python main.py -``` - -## Testing with azd - -**Bash:** ```bash azd ai agent invoke --local '{"message": "What time is it right now?"}' ``` -**PowerShell:** -```powershell -azd ai agent invoke --local '{\"message\": \"What time is it right now?\"}' -``` - -## Testing with curl +Or invoke directly with curl (multi-turn): ```bash # Turn 1 — ask for the time (triggers tool call) @@ -99,19 +72,14 @@ curl -N -X POST 'http://localhost:8088/invocations?agent_session_id=s1' \ -d '{"message": "Add 100 to that result"}' ``` -## Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +### Deploy to Foundry ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke '{"message": "What time is it right now?"}' @@ -125,19 +93,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md b/samples/python/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md index 0b9d4b98f..6c30b6162 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/notetaking-agent/README.md @@ -23,100 +23,52 @@ A note-taking agent built with `azure-ai-agentserver-invocations` and Azure Open | `FOUNDRY_PROJECT_ENDPOINT` | Foundry project endpoint (auto-injected when deployed) | `https://account.services.ai.azure.com/api/projects/proj` | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment name | `gpt-5.4-mini` | -## Run Locally +## Option 1: Azure Developer CLI (`azd`) -### Using `azd` +### Run the agent locally ```bash azd ai agent run ``` -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup +### Invoke the local agent -```bash -# Install dependencies -pip install -r requirements.txt - -# Set environment variables -export FOUNDRY_PROJECT_ENDPOINT="https://account.services.ai.azure.com/api/projects/proj" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" - -# Start the agent -python main.py -``` - -## Test with azd - -**Bash:** ```bash azd ai agent invoke --local '{"message": "save a note - book reservation for dinner"}' ``` -**PowerShell:** -```powershell -azd ai agent invoke --local '{\"message\": \"save a note - book reservation for dinner\"}' -``` - -## Test with curl - -### Save a note +Or invoke directly with curl: ```bash +# Save a note curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "save a note - book reservation for dinner"}' -``` -### Save another note - -```bash +# Save another note curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "save a note - buy groceries for the weekend"}' -``` - -### Get all notes -```bash +# Get all notes curl -N -X POST "http://localhost:8088/invocations?agent_session_id=my-session" \ -H "Content-Type: application/json" \ -d '{"message": "show me all my notes"}' -``` - -### New session (isolated) -```bash +# New session (isolated) curl -N -X POST "http://localhost:8088/invocations?agent_session_id=another-session" \ -H "Content-Type: application/json" \ -d '{"message": "show me my notes"}' ``` -## Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +### Deploy to Foundry ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke '{"message": "save a note - book reservation for dinner"}' @@ -130,19 +82,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## File Structure diff --git a/samples/python/hosted-agents/bring-your-own/invocations/toolbox/README.md b/samples/python/hosted-agents/bring-your-own/invocations/toolbox/README.md index 909ab261a..898cf8b46 100644 --- a/samples/python/hosted-agents/bring-your-own/invocations/toolbox/README.md +++ b/samples/python/hosted-agents/bring-your-own/invocations/toolbox/README.md @@ -114,13 +114,34 @@ The agent starts on `http://localhost:8088`.

Using the Foundry Toolkit VS Code Extension

 -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +**Prerequisites** -Chat with a running agent using the **Agent Inspector**: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test.
diff --git a/samples/python/hosted-agents/bring-your-own/responses/background-agent/README.md b/samples/python/hosted-agents/bring-your-own/responses/background-agent/README.md index 3317fb447..6507892f2 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/background-agent/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/background-agent/README.md @@ -8,7 +8,7 @@ This sample demonstrates a long-running agent built with [azure-ai-agentserver-r The agent receives a request via `POST /responses` with `"background": true`. The server returns immediately while the handler calls Azure OpenAI in the background, streaming response tokens as `text.delta` events. The caller polls `GET /responses/{id}` until the response reaches a terminal status (`completed`, `failed`, or `incomplete`). In-flight requests can be cancelled via `POST /responses/{id}/cancel`. -## Running Locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites @@ -16,7 +16,7 @@ The agent receives a request via `POST /responses` with `"background": true`. Th - Azure CLI installed and authenticated (`az login`) - Foundry project with a deployed model -### Using `azd` +### Run the agent locally ```bash azd ai agent run @@ -24,49 +24,16 @@ azd ai agent run The agent starts on `http://localhost:8088/`. -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # then edit values (skip if .env already exists) -export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini" -python main.py -``` - -The agent starts on `http://localhost:8088/`. - -## Invoke with azd - -### Local +### Invoke the local agent ```bash azd ai agent invoke --local "Analyze the impact of AI on healthcare" ``` -### Remote (after `azd up`) - -```bash -azd ai agent invoke "Analyze the impact of AI on healthcare" -``` - -### Test — Background Mode +Or test background and synchronous modes directly with curl: ```bash -# Submit a background research analysis +# Background mode — submit a research analysis curl -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ -d '{"model": "research", "input": "Analyze the impact of AI on healthcare", "background": true, "store": true}' @@ -76,29 +43,23 @@ curl http://localhost:8088/responses/ # Cancel an in-flight request curl -X POST http://localhost:8088/responses//cancel -``` - -### Test — Default Mode (Synchronous) -```bash +# Default (synchronous) mode curl -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ -d '{"model": "research", "input": "Analyze the impact of AI on healthcare"}' ``` -## Deploying the Agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke "Analyze the impact of AI on healthcare" @@ -112,19 +73,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/README.md b/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/README.md index 91b2be3ef..bf57f45ed 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/README.md @@ -114,13 +114,34 @@ The agent starts on `http://localhost:8088`.

Using the Foundry Toolkit VS Code Extension

 -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +**Prerequisites** -Chat with a running agent using the **Agent Inspector**: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test.
diff --git a/samples/python/hosted-agents/bring-your-own/responses/browser-automation/README.md b/samples/python/hosted-agents/bring-your-own/responses/browser-automation/README.md index af041db6f..6f898f625 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/browser-automation/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/browser-automation/README.md @@ -108,9 +108,36 @@ curl -sS -X POST http://localhost:8088/responses \ -d '{"input": "Go to https://example.com and tell me the page title"}' | jq . ``` -### Test in Agent Inspector +### Test in VS Code (Foundry Toolkit) -Open **Agent Inspector** in VS Code (Command Palette → **Foundry Toolkit: Open Agent Inspector**) to interactively send messages. +**Prerequisites** + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ## Deploying to Foundry diff --git a/samples/python/hosted-agents/bring-your-own/responses/env-vars-agent/README.md b/samples/python/hosted-agents/bring-your-own/responses/env-vars-agent/README.md index b64e0af8b..5c57662f3 100755 --- a/samples/python/hosted-agents/bring-your-own/responses/env-vars-agent/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/env-vars-agent/README.md @@ -127,9 +127,36 @@ curl -N -X POST http://localhost:8088/responses \ -d '{"input": "did SECRET_KEY resolve? it is a credentials placeholder.", "stream": true}' ``` -#### 3. Test in Agent Inspector +#### 3. Test in VS Code (Foundry Toolkit) -Once the agent is running, open **Agent Inspector** in VS Code to interactively send messages and view responses. +**Prerequisites** + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. ``` what is TARGET? it is the target of an ApiKey connection. diff --git a/samples/python/hosted-agents/bring-your-own/responses/hello-world/README.md b/samples/python/hosted-agents/bring-your-own/responses/hello-world/README.md index f938294ab..bb82ebce1 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/hello-world/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/hello-world/README.md @@ -89,13 +89,34 @@ Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the F

Using the Foundry Toolkit VS Code Extension

 -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. +**Prerequisites** -Chat with a running agent using the **Agent Inspector**: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test.
diff --git a/samples/python/hosted-agents/bring-your-own/responses/langgraph-chat/README.md b/samples/python/hosted-agents/bring-your-own/responses/langgraph-chat/README.md index 43ab973b2..9056c7956 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/langgraph-chat/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/langgraph-chat/README.md @@ -45,42 +45,21 @@ via `previous_response_id` — no need for an in-memory session store. | `FOUNDRY_PROJECT_ENDPOINT` | Yes | — | Foundry project endpoint URL | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | — | Model deployment name declared in `azure.yaml` | -## Running locally +## Option 1: Azure Developer CLI (`azd`) -### Using `azd` +### Run the agent locally ```bash azd ai agent run ``` -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -cp .env.example .env # then edit values (skip if .env already exists) -pip install -r requirements.txt -python main.py -``` - -## Testing with azd +### Invoke the local agent ```bash azd ai agent invoke --local "What time is it right now?" ``` -## Testing with curl +Or invoke directly with curl (multi-turn): ```bash # Turn 1 — ask for the time (triggers tool call) @@ -99,19 +78,14 @@ curl -N -X POST http://localhost:8088/responses \ -d '{"model": "chat", "input": "Add 100 to that result", "previous_response_id": "", "stream": true}' ``` -## Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +### Deploy to Foundry ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke "What time is it right now?" @@ -125,19 +99,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox-user-identity/README.md b/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox-user-identity/README.md index 5fd93b72f..8495b5772 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox-user-identity/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox-user-identity/README.md @@ -84,6 +84,40 @@ Invoke-RestMethod -Method POST http://localhost:8088/responses ` -Body '{"input": "What tools do you have?"}' ``` +
+

Using the Foundry Toolkit VS Code Extension

 + +**Prerequisites** + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +
+ ## Deploy as a Hosted Agent ### Setup diff --git a/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox/README.md b/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox/README.md index 63064a968..972b2278d 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox/README.md @@ -75,6 +75,40 @@ Invoke-RestMethod -Method POST http://localhost:8088/responses ` -Body '{"input": "What tools do you have?"}' ``` +
+

Using the Foundry Toolkit VS Code Extension

 + +**Prerequisites** + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +**Set up the Python virtual environment** + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +**Run and debug the agent** + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +**Or run manually, then open the Inspector** + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +
+ ## Deploy as a Hosted Agent ### Setup diff --git a/samples/python/hosted-agents/bring-your-own/responses/notetaking-agent/README.md b/samples/python/hosted-agents/bring-your-own/responses/notetaking-agent/README.md index 9d723ed64..bb7713910 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/notetaking-agent/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/notetaking-agent/README.md @@ -23,97 +23,47 @@ A note-taking agent built with `azure-ai-agentserver-responses` and Azure OpenAI | `FOUNDRY_PROJECT_ENDPOINT` | Foundry project endpoint URL | `https://your-project.services.ai.azure.com/api/projects/your-project` | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment name declared in `azure.yaml` | `gpt-5.4-mini` | -## Run Locally +## Option 1: Azure Developer CLI (`azd`) -### Using `azd` +### Run the agent locally ```bash azd ai agent run ``` -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -# Copy and edit environment file -cp .env.example .env # skip if .env already exists - -# Install dependencies -pip install -r requirements.txt - -# Start the agent -python main.py -``` - -## Test with azd +### Invoke the local agent ```bash azd ai agent invoke --local "save a note - book reservation for dinner" ``` -## Test with curl - -### Save a note +Or invoke directly with curl: ```bash +# Save a note curl -N -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ - -d '{ - "input": "save a note - book reservation for dinner", - "stream": true, - "agent_session_id": "my-session" - }' -``` - -### Save another note + -d '{"input": "save a note - book reservation for dinner", "stream": true, "agent_session_id": "my-session"}' -```bash +# Save another note curl -N -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ - -d '{ - "input": "save a note - buy groceries for the weekend", - "stream": true, - "agent_session_id": "my-session" - }' -``` + -d '{"input": "save a note - buy groceries for the weekend", "stream": true, "agent_session_id": "my-session"}' -### Get all notes - -```bash +# Get all notes curl -N -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ - -d '{ - "input": "show me all my notes", - "stream": true, - "agent_session_id": "my-session" - }' + -d '{"input": "show me all my notes", "stream": true, "agent_session_id": "my-session"}' ``` -## Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +### Deploy to Foundry ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent ```bash azd ai agent invoke "save a note - book reservation for dinner" @@ -127,19 +77,43 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## File Structure diff --git a/samples/python/hosted-agents/bring-your-own/responses/openai-agents-sdk/README.md b/samples/python/hosted-agents/bring-your-own/responses/openai-agents-sdk/README.md index 1c86a7dff..c13141810 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/openai-agents-sdk/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/openai-agents-sdk/README.md @@ -21,7 +21,7 @@ Authentication uses `DefaultAzureCredential` via `AIProjectClient` — the same | `FOUNDRY_PROJECT_ENDPOINT` | Yes | Foundry project endpoint (auto-injected in hosted containers; set by `azd ai agent run` locally) | | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Yes | Model deployment name in your Foundry project | -## Running Locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites @@ -29,7 +29,7 @@ Authentication uses `DefaultAzureCredential` via `AIProjectClient` — the same - A Microsoft Foundry project with a model deployment (e.g. `gpt-4o-mini`) - Azure CLI logged in (`az login`) or another credential supported by `DefaultAzureCredential` -### Using `azd` +### Run the agent locally `azd ai agent run` automatically injects `FOUNDRY_PROJECT_ENDPOINT` and starts the agent: @@ -39,46 +39,14 @@ azd ai agent run The agent starts on `http://localhost:8088/`. -
-

Using the Foundry Toolkit VS Code Extension

 - -The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. - -Chat with a running agent using the **Agent Inspector**: - -1. Start the agent locally first using **Using `azd`** or **Manual setup** above. The agent listens on `http://localhost:8088/`. -2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -3. The Inspector auto-connects to the running agent. Send messages to chat with the agent and watch the streamed responses. - -
- -### Manual setup - -```bash -pip install -r requirements.txt -cp .env.example .env # then set FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME (skip if .env already exists) -python main.py -``` - -The agent starts on `http://localhost:8088/`. - -## Invoke with azd - -### Local +### Invoke the local agent **Bash:** - ```bash azd ai agent invoke --local "What can you help me with?" ``` -**PowerShell:** - -```powershell -azd ai agent invoke --local '{\"input\": \"What can you help me with?\"}' -``` - -### Test with curl +Or invoke directly with curl: ```bash # First message @@ -92,37 +60,22 @@ curl -sS -N -X POST "http://localhost:8088/responses" \ -d '{"input": "What hosted agent options does it offer?", "agent_session_id": "chat-001", "stream": true}' ``` -### Streaming Behavior +### Deploy to Foundry -The responses protocol SDK emits lifecycle and content events automatically when -`TextResponse(...)` is returned. - -## Deploying the Agent to Microsoft Foundry - -Once you've tested locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash -# Provision Azure resources (skip if already done during local setup) azd provision - -# Build, push, and deploy the agent to Foundry azd deploy ``` -After deploying, invoke the agent running in Foundry: +### Invoke the deployed agent **Bash:** - ```bash azd ai agent invoke '{"input": "What can you help me with?"}' ``` -**PowerShell:** - -```powershell -azd ai agent invoke '{\"input\": \"What can you help me with?\"}' -``` - To stream logs from the running agent: ```bash @@ -131,21 +84,50 @@ azd ai agent monitor For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. +## Streaming behavior + +The responses protocol SDK emits lifecycle and content events automatically when +`TextResponse(...)` is returned. + ## Troubleshooting ### `FOUNDRY_PROJECT_ENDPOINT` not set diff --git a/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/README.md b/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/README.md index 56595eeea..31dd338e1 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/README.md @@ -108,12 +108,40 @@ azd deploy azd ai agent invoke "I ordered a laptop 3 days ago and haven't received a shipping confirmation. Order #12345." ``` -## Option 2: Foundry Toolkit VS Code Extension +## Option 2: VS Code (Foundry Toolkit) -1. Clone this repo and open this sample folder in VS Code. -2. Start locally: `azd ai agent run` -3. Open Command Palette → **Foundry Toolkit: Open Agent Inspector** to chat. -4. When ready: **Foundry Toolkit: Deploy Hosted Agent**. +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +Run **Foundry Toolkit: Deploy Hosted Agent** and follow the wizard. ## Running Optimization diff --git a/samples/python/hosted-agents/bring-your-own/responses/optimization-hello-world/README.md b/samples/python/hosted-agents/bring-your-own/responses/optimization-hello-world/README.md index 1b143ef07..2962d3b88 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/optimization-hello-world/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/optimization-hello-world/README.md @@ -87,12 +87,40 @@ azd deploy azd ai agent invoke "Hello! What can you help me with?" ``` -## Option 2: Foundry Toolkit VS Code Extension +## Option 2: VS Code (Foundry Toolkit) -1. Clone this repo and open this sample folder in VS Code. -2. Start locally: `azd ai agent run` -3. Open Command Palette → **Foundry Toolkit: Open Agent Inspector** to chat with the agent. -4. When ready: **Foundry Toolkit: Deploy Hosted Agent**. +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +Run **Foundry Toolkit: Deploy Hosted Agent** and follow the wizard. ## Running Optimization diff --git a/samples/python/hosted-agents/bring-your-own/responses/session-multiplexing/README.md b/samples/python/hosted-agents/bring-your-own/responses/session-multiplexing/README.md index 0263cafd3..aa9804924 100644 --- a/samples/python/hosted-agents/bring-your-own/responses/session-multiplexing/README.md +++ b/samples/python/hosted-agents/bring-your-own/responses/session-multiplexing/README.md @@ -52,7 +52,7 @@ If a user has no sticky mapping yet, the caller reuses an existing session with The agent is hosted using the [Azure AI AgentServer Responses SDK](https://pypi.org/project/azure-ai-agentserver-responses/), which provisions a REST API endpoint compatible with the OpenAI Responses protocol. -## Running the agent locally +## Option 1: Azure Developer CLI (`azd`) ### Prerequisites @@ -103,11 +103,7 @@ source .venv/bin/activate pip install -r requirements.txt ``` -### Running the sample - -Run and test hosted agents locally with the Azure Developer CLI (`azd`) or the Foundry Toolkit VS Code extension. - -#### Using `azd` +### Run the agent locally ```bash mkdir session-multiplexing-agent && cd session-multiplexing-agent @@ -122,24 +118,20 @@ azd ai agent run The agent starts on `http://localhost:8088/`. Local requests do not include hosted protocol 2.0.0 platform context, so the handler fails closed until `get_request_context().user_id` and `get_request_context().call_id` are present. -#### Manual setup - -If running without `azd`, set environment variables manually, then: - -```bash -python main.py -``` +To run without `azd`, set the required environment variables manually, then start the agent with `python main.py`. -## Deploying the agent to Microsoft Foundry +### Deploy to Foundry -Once you've tested startup locally, deploy to Microsoft Foundry: +Once tested locally, deploy to Microsoft Foundry: ```bash azd provision azd deploy ``` -After deployment, invoke the agent running in Foundry: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent ```bash azd ai agent invoke "Remember that my code word is BLUE-LANTERN" @@ -151,7 +143,44 @@ To stream logs from the running agent: azd ai agent monitor ``` -For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Install dependencies in the virtual environment: + + ```bash + # use uv to accelerate + pip install uv + uv pip install -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Testing session multiplexing after deployment diff --git a/samples/python/hosted-agents/langgraph/README.md b/samples/python/hosted-agents/langgraph/README.md index b376f2a82..9cd57bf86 100644 --- a/samples/python/hosted-agents/langgraph/README.md +++ b/samples/python/hosted-agents/langgraph/README.md @@ -152,9 +152,10 @@ cd foundry-samples/samples/python/hosted-agents/langgraph source .venv/bin/activate ``` -2. Install dependencies: +2. Ensure `pip` is version 26.1 or newer (check with `pip --version`); older versions fail to resolve the samples' dependencies. Upgrade if needed, then install: ```bash + python -m pip install --upgrade pip pip install -r requirements.txt ``` diff --git a/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/README.md b/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/README.md index 968c8fbf7..5f4183758 100644 --- a/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/README.md +++ b/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/README.md @@ -21,42 +21,67 @@ The compiled graph is hosted with `InvocationsHostServer`, which exposes the Inv Multi-turn continuity is provided by the LangGraph `MemorySaver` checkpointer: the host wires the resolved `agent_session_id` into `RunnableConfig.configurable.thread_id`, so each session's history is preserved across turns. Replace `MemorySaver` with a durable checkpointer (Redis, Cosmos DB, etc.) for production. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Send a POST request with a JSON body containing a `"message"` field. The `-i` flag includes the response headers, which carry the `x-agent-session-id` header you need for multi-turn conversations: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -# Turn 1 — triggers the get_current_time tool -curl -i -X POST http://localhost:8088/invocations \ - -H "Content-Type: application/json" \ - -d '{"message": "What time is it right now?"}' +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/azure.yaml ``` -```powershell -# Turn 1 — triggers the get_current_time tool (response object exposes both Headers and Content) -Invoke-WebRequest -Uri http://localhost:8088/invocations -Method POST -ContentType "application/json" -Body '{"message": "What time is it right now?"}' +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision ``` -Example response: +### Run the agent locally +```bash +azd ai agent run ``` -HTTP/1.1 200 -content-type: application/json -x-agent-session-id: 9370b9d4-cd13-4436-a57f-03b843ac0e17 -{"response": "The current UTC time is ..."} +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, invoke the running agent: + +```bash +azd ai agent invoke --local '{"message": "What time is it right now?"}' ``` -Take the `x-agent-session-id` from the previous response and pass it as a URL parameter on the next requests to continue the conversation: +Or invoke directly with curl. The `-i` flag surfaces the `x-agent-session-id` response header you need for multi-turn conversations: ```bash -# Turn 2 — triggers the calculator tool +# Turn 1 — triggers the get_current_time tool (note the x-agent-session-id response header) +curl -i -X POST http://localhost:8088/invocations \ + -H "Content-Type: application/json" \ + -d '{"message": "What time is it right now?"}' + +# Turn 2 — pass the session id from Turn 1; triggers the calculator tool curl -X POST 'http://localhost:8088/invocations?agent_session_id=REPLACE_WITH_SESSION_ID' \ -H "Content-Type: application/json" \ -d '{"message": "What is 42 * 17?"}' @@ -67,17 +92,7 @@ curl -X POST 'http://localhost:8088/invocations?agent_session_id=REPLACE_WITH_SE -d '{"message": "Add 100 to that result."}' ``` -```powershell -# Turn 2 — triggers the calculator tool -(Invoke-WebRequest -Uri "http://localhost:8088/invocations?agent_session_id=REPLACE_WITH_SESSION_ID" -Method POST -ContentType "application/json" -Body '{"message": "What is 42 * 17?"}').Content - -# Turn 3 — context recall (no tool call) -(Invoke-WebRequest -Uri "http://localhost:8088/invocations?agent_session_id=REPLACE_WITH_SESSION_ID" -Method POST -ContentType "application/json" -Body '{"message": "Add 100 to that result."}').Content -``` - -### Streaming - -Add `"stream": true` to receive per-token text deltas as SSE `data:` lines, followed by `event: done`: +Add `"stream": true` to receive per-token SSE deltas, followed by `event: done`: ```bash curl -N -X POST http://localhost:8088/invocations \ @@ -85,42 +100,63 @@ curl -N -X POST http://localhost:8088/invocations \ -d '{"message": "Count to 5.", "stream": true}' ``` -```powershell -# Note: Invoke-WebRequest buffers the full response; the SSE deltas are visible in .Content but not delivered incrementally. -(Invoke-WebRequest -Uri http://localhost:8088/invocations -Method POST -ContentType "application/json" -Body '{"message": "Count to 5.", "stream": true}').Content +### Deploy to Foundry + +Once tested locally, deploy to Microsoft Foundry: + +```bash +azd deploy ``` -Invoke with `azd`: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -```powershell -azd ai agent invoke --local '{"message": "What time is it right now?"}' +### Invoke the deployed agent + +```bash +azd ai agent invoke '{"message": "What time is it right now?"}' ``` -### Test in Agent Inspector +## Option 2: VS Code (Foundry Toolkit) -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Prerequisites -Type the following message in Inspector: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -``` -What time is it right now? -``` +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -## Deploying the Agent to Foundry +### Or run manually, then open the Inspector -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/src/langgraph-chat-invocations/main.py b/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/src/langgraph-chat-invocations/main.py index 33aae1a80..59e82e41b 100644 --- a/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/src/langgraph-chat-invocations/main.py +++ b/samples/python/hosted-agents/langgraph/invocations/01-langgraph-chat/src/langgraph-chat-invocations/main.py @@ -64,6 +64,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/README.md b/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/README.md index 446f47497..a651bde67 100644 --- a/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/README.md +++ b/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/README.md @@ -19,31 +19,66 @@ The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenA Conversation state is managed server-side by the platform via `previous_response_id` — there is no application-side session storage. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Send a POST request to the server with a JSON body containing an `input` field: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -# Turn 1 — triggers the get_current_time tool -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "What time is it right now?"}' +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/azure.yaml ``` -```powershell -# Turn 1 — triggers the get_current_time tool -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "What time is it right now?"}').Content +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision ``` -The server responds with a JSON object containing the response text and a response ID. Use that response ID to continue the conversation: +### Run the agent locally ```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, invoke the running agent: + +```bash +azd ai agent invoke --local "What time is it right now?" +``` + +Or invoke directly with curl (multi-turn): + +```bash +# Turn 1 — triggers the get_current_time tool +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "What time is it right now?"}' + # Turn 2 — chain via previous_response_id; triggers the calculator tool curl -X POST http://localhost:8088/responses \ -H "Content-Type: application/json" \ @@ -55,39 +90,63 @@ curl -X POST http://localhost:8088/responses \ -d '{"input": "Add 100 to that result.", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}' ``` -```powershell -# Turn 2 — chain via previous_response_id; triggers the calculator tool -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "What is 42 * 17?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}').Content +### Deploy to Foundry -# Turn 3 — context recall (no tool call) -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Add 100 to that result.", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}').Content -``` +Once tested locally, deploy to Microsoft Foundry: -### Test in Agent Inspector +```bash +azd deploy +``` -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -Type the following message in Inspector: +### Invoke the deployed agent +```bash +azd ai agent invoke "What time is it right now?" ``` -What time is it right now? -``` -## Deploying the Agent to Foundry +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/src/langgraph-chat-responses/main.py b/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/src/langgraph-chat-responses/main.py index 487c9107d..ddd574a58 100644 --- a/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/src/langgraph-chat-responses/main.py +++ b/samples/python/hosted-agents/langgraph/responses/01-langgraph-chat/src/langgraph-chat-responses/main.py @@ -61,6 +61,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/README.md b/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/README.md index a8ee22eba..0f2098e17 100644 --- a/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/README.md +++ b/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/README.md @@ -49,15 +49,57 @@ The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenA See [main.py](src/toolbox-langgraph/main.py) for the full implementation. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Send a POST request to the server with a JSON body containing an `input` field: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/azure.yaml +``` + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project, model deployment, and toolbox, provision them. `azd provision` creates the toolbox (`my-toolbox` by default) referenced by `TOOLBOX_NAME`: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, send a query to the agent: + +```bash +azd ai agent invoke --local "How do I create a Foundry project with the Azure CLI?" +``` + +Or invoke directly with curl: ```bash # Tool discovery @@ -76,50 +118,65 @@ curl -X POST http://localhost:8088/responses \ -d '{"input": "How do I create a Foundry project with the Azure CLI?"}' ``` -```powershell -# Tool discovery -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "What tools do you have?"}').Content +### Deploy to Foundry -# web_search -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "What is the latest stable Python release?"}').Content +Deploy the agent to Microsoft Foundry: -# Microsoft Learn MCP -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "How do I create a Foundry project with the Azure CLI?"}').Content +```bash +azd deploy ``` -Invoke with `azd`: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -```powershell -azd ai agent invoke --local "How do I create a Foundry project with the Azure CLI?" +### Invoke the deployed agent + +```bash +azd ai agent invoke "How do I create a Foundry project with the Azure CLI?" ``` -### Test in Agent Inspector +## Option 2: VS Code (Foundry Toolkit) -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Prerequisites -Type the following message in Inspector: +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -``` -How do I create a Foundry project with the Azure CLI? -``` +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -## Deploying the Agent to Foundry +### Or run manually, then open the Inspector -Follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +1. Set the required environment variables (including `TOOLBOX_NAME`), and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. ## Troubleshooting diff --git a/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/src/toolbox-langgraph/main.py b/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/src/toolbox-langgraph/main.py index 23b87d190..90afd9376 100644 --- a/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/src/toolbox-langgraph/main.py +++ b/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox/src/toolbox-langgraph/main.py @@ -60,6 +60,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/04-mcp/README.md b/samples/python/hosted-agents/langgraph/responses/04-mcp/README.md index 6699e6a10..eee33e439 100644 --- a/samples/python/hosted-agents/langgraph/responses/04-mcp/README.md +++ b/samples/python/hosted-agents/langgraph/responses/04-mcp/README.md @@ -29,15 +29,63 @@ The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenA azd env set GITHUB_PAT "" ``` -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. This sample additionally requires `GITHUB_PAT` (and optionally `MCP_SERVER_URL` if you target a different MCP server). +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Ask the agent a question that exercises one of the GitHub MCP tools: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/04-mcp/azure.yaml +``` + +This sample requires a GitHub PAT (see [Prerequisites](#prerequisites)). Set it in the azd environment so `azd` can resolve the `${GITHUB_PAT}` placeholder in `azure.yaml`: + +```bash +azd env set GITHUB_PAT "" +``` + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +In a separate terminal, ask the agent a question that exercises one of the GitHub MCP tools: + +```bash +azd ai agent invoke --local "List my 5 most recently updated GitHub repos." +``` + +Or invoke directly with curl: ```bash # List repositories @@ -51,51 +99,69 @@ curl -X POST http://localhost:8088/responses \ -d '{"input": "Search GitHub issues mentioning langchain-azure."}' ``` -```powershell -# List repositories -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "List my 5 most recently updated GitHub repos."}').Content +Intermediate `function_call` / `function_call_output` items are surfaced for every MCP tool the agent invokes — same shape as the local-tools sample, but the tool execution happens inside the remote MCP server. -# Search issues -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Search GitHub issues mentioning langchain-azure."}').Content +### Deploy to Foundry + +Make sure `GITHUB_PAT` is set in the azd environment (see [Prerequisites](#prerequisites)), then deploy to Microsoft Foundry: + +```bash +azd deploy ``` -Invoke with `azd`: +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -```powershell -azd ai agent invoke --local "List my 5 most recently updated GitHub repos." +### Invoke the deployed agent + +```bash +azd ai agent invoke "List my 5 most recently updated GitHub repos." ``` -Intermediate `function_call` / `function_call_output` items are surfaced for every MCP tool the agent invokes — same shape as the local-tools sample, but the tool execution happens inside the remote MCP server. +## Option 2: VS Code (Foundry Toolkit) -### Test in Agent Inspector +### Prerequisites -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. -Type the following message in Inspector: +### Set up the Python virtual environment -``` -List my 5 most recently updated GitHub repos. -``` +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: -## Targeting a different MCP server + ```bash + python -m pip install --upgrade pip + ``` -Set `MCP_SERVER_URL` to any HTTP-transport MCP endpoint and adjust `GITHUB_PAT` (or the `Authorization` header logic in [main.py](src/langgraph-mcp-responses/main.py)) to match its auth scheme. +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` -## Deploying the Agent to Foundry +### Run and debug the agent -Make sure `GITHUB_PAT` is set in the azd environment (see [Prerequisites](#prerequisites)), then follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +Set `GITHUB_PAT` in `.env` (see [.env.example](src/langgraph-mcp-responses/.env.example)), then press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. -### Deploying with the Foundry Toolkit VS Code Extension +### Or run manually, then open the Inspector -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Set `GITHUB_PAT` and the other required environment variables, and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + +## Targeting a different MCP server + +Set `MCP_SERVER_URL` to any HTTP-transport MCP endpoint and adjust `GITHUB_PAT` (or the `Authorization` header logic in [main.py](src/langgraph-mcp-responses/main.py)) to match its auth scheme. diff --git a/samples/python/hosted-agents/langgraph/responses/04-mcp/src/langgraph-mcp-responses/main.py b/samples/python/hosted-agents/langgraph/responses/04-mcp/src/langgraph-mcp-responses/main.py index 40f91dc26..b1ff6284a 100644 --- a/samples/python/hosted-agents/langgraph/responses/04-mcp/src/langgraph-mcp-responses/main.py +++ b/samples/python/hosted-agents/langgraph/responses/04-mcp/src/langgraph-mcp-responses/main.py @@ -43,6 +43,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/05-workflows/README.md b/samples/python/hosted-agents/langgraph/responses/05-workflows/README.md index 0d1c26d6a..dc67a9f04 100644 --- a/samples/python/hosted-agents/langgraph/responses/05-workflows/README.md +++ b/samples/python/hosted-agents/langgraph/responses/05-workflows/README.md @@ -23,57 +23,123 @@ See [main.py](src/langgraph-workflows-responses/main.py) for the full implementa The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenAI-compatible Responses endpoint at `/responses` and handles conversation history, streaming lifecycle events, and message surfacing automatically. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Send a POST request to the server with a JSON body containing an `"input"` field: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "Create a slogan for a new electric SUV that is affordable and fun to drive."}' +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/05-workflows/azure.yaml +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Create a slogan for a new electric SUV that is affordable and fun to drive."}').Content +### Run the agent locally + +```bash +azd ai agent run ``` -Invoke with `azd`: +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent -```powershell +In a separate terminal, invoke the running agent: + +```bash azd ai agent invoke --local "Create a slogan for a new electric SUV that is affordable and fun to drive." ``` -### Test in Agent Inspector +Or invoke directly with curl: -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Create a slogan for a new electric SUV that is affordable and fun to drive."}' +``` + +### Deploy to Foundry -Type the following message in Inspector: +Once tested locally, deploy to Microsoft Foundry: +```bash +azd deploy ``` -Create a slogan for a new electric SUV that is affordable and fun to drive. + +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "Create a slogan for a new electric SUV that is affordable and fun to drive." ``` -## Deploying the Agent to Foundry +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/python/hosted-agents/langgraph/responses/05-workflows/src/langgraph-workflows-responses/main.py b/samples/python/hosted-agents/langgraph/responses/05-workflows/src/langgraph-workflows-responses/main.py index 9bd8c51da..a434526d3 100644 --- a/samples/python/hosted-agents/langgraph/responses/05-workflows/src/langgraph-workflows-responses/main.py +++ b/samples/python/hosted-agents/langgraph/responses/05-workflows/src/langgraph-workflows-responses/main.py @@ -61,6 +61,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/06-files/README.md b/samples/python/hosted-agents/langgraph/responses/06-files/README.md index a58bdeb7a..d470678d1 100644 --- a/samples/python/hosted-agents/langgraph/responses/06-files/README.md +++ b/samples/python/hosted-agents/langgraph/responses/06-files/README.md @@ -27,44 +27,127 @@ See [main.py](src/langgraph-files-responses/main.py) for the full implementation The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenAI-compatible Responses endpoint at `/responses` and handles conversation history, streaming lifecycle events, and tool-call surfacing automatically. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. This sample additionally requires `TOOLBOX_NAME` to point at a Foundry Toolbox that exposes the `code_interpreter` tool. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Ask the agent to discover and analyze the bundled quarterly report: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "Find the quarterly report under `{cwd}/resources` and tell me the difference of revenue between q1 2026 and q1 2025."}' +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/06-files/azure.yaml ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Find the quarterly report under `{cwd}/resources` and tell me the difference of revenue between q1 2026 and q1 2025."}').Content +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment, provision them. This sample also requires `TOOLBOX_NAME` to point at a Foundry Toolbox that exposes the `code_interpreter` tool: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run ``` -Invoke with `azd`: +The agent host will start on `http://localhost:8088`. -```powershell +### Invoke the local agent + +In a separate terminal, ask the agent to discover and analyze the bundled quarterly report: + +```bash azd ai agent invoke --local "Find the quarterly report under \`{cwd}/resources\` and tell me the difference of revenue between q1 2026 and q1 2025." ``` -The agent will call `get_cwd` and `list_files` to locate the file, `read_file` to load its contents, and `code_interpreter` to compute the revenue delta. +Or invoke directly with curl: + +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Find the quarterly report under `{cwd}/resources` and tell me the difference of revenue between q1 2026 and q1 2025."}' +``` -### Test in Agent Inspector +The agent will call `get_cwd` and `list_files` to locate the file, `read_file` to load its contents, and `code_interpreter` to compute the revenue delta. -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Deploy to Foundry -Type the following message in Inspector: +Deploy the agent to Microsoft Foundry: +```bash +azd deploy ``` -Find the quarterly report under `{cwd}/resources` and tell me the difference of revenue between q1 2026 and q1 2025. + +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "Find the quarterly report under \`{cwd}/resources\` and tell me the difference of revenue between q1 2026 and q1 2025." ``` +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables (including `TOOLBOX_NAME`), and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + ## Uploading files to a hosted session After deploying the agent to Foundry, uploaded session files are mounted into the agent's working directory, where the same local tools can read them. Upload a file to the current session with: @@ -78,22 +161,3 @@ Then ask the agent about it: ```bash azd ai agent invoke "Read the quarterly report I just uploaded and summarize the year-over-year revenue change." ``` - -## Deploying the Agent to Foundry - -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. - -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. -5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/python/hosted-agents/langgraph/responses/06-files/src/langgraph-files-responses/main.py b/samples/python/hosted-agents/langgraph/responses/06-files/src/langgraph-files-responses/main.py index fc66cbe71..bd5647f87 100644 --- a/samples/python/hosted-agents/langgraph/responses/06-files/src/langgraph-files-responses/main.py +++ b/samples/python/hosted-agents/langgraph/responses/06-files/src/langgraph-files-responses/main.py @@ -89,6 +89,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/README.md b/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/README.md index 723805f4b..ebdb0fcdf 100644 --- a/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/README.md +++ b/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/README.md @@ -43,17 +43,53 @@ The Responses host emits two paired output items for each pause, both keyed by t The compiled graph is hosted with `ResponsesHostServer`, which exposes the OpenAI-compatible Responses endpoint at `/responses` and handles conversation history, interrupt serialization, and streaming lifecycle events automatically. -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -### Step 1 — Submit the task +3. Authenticate: -Send a POST request with a `conversation.id` so the checkpoint can be matched on subsequent requests: + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/azure.yaml +``` + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision +``` + +### Run the agent locally + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +### Invoke the local agent + +This sample uses a human-in-the-loop approval flow: submit a task, then approve, reject, or revise the proposed draft. Run the requests below from a separate terminal. + +**Step 1 — Submit the task.** Send a POST request with a `conversation.id` so the checkpoint can be matched on subsequent requests: ```bash curl -X POST http://localhost:8088/responses \ @@ -61,10 +97,6 @@ curl -X POST http://localhost:8088/responses \ -d '{"input": "Draft a marketing email for our new AI product launch.", "conversation": {"id": "demo-hitl-1"}}' ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Draft a marketing email for our new AI product launch.", "conversation": {"id": "demo-hitl-1"}}').Content -``` - The response `output` will contain an `mcp_approval_request` whose `arguments` JSON describes the proposed draft: ```json @@ -73,9 +105,9 @@ The response `output` will contain an `mcp_approval_request` whose `arguments` J Note the `id` field of the `mcp_approval_request` item — you will reference it as `approval_request_id` (or as the `call_id` of the paired `function_call`) in the next request. -### Step 2 — Send a decision +**Step 2 — Send a decision.** -**Approve** — the host resumes the graph and emits the final draft: +*Approve* — the host resumes the graph and emits the final draft: ```bash curl -X POST http://localhost:8088/responses \ @@ -83,11 +115,7 @@ curl -X POST http://localhost:8088/responses \ -d '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "mcp_approval_response", "approval_request_id": "", "approve": true}]}' ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "mcp_approval_response", "approval_request_id": "", "approve": true}]}').Content -``` - -**Reject** — the turn ends with `response.failed` `code="interrupt_rejected"`; the pending interrupt remains in the checkpoint: +*Reject* — the turn ends with `response.failed` `code="interrupt_rejected"`; the pending interrupt remains in the checkpoint: ```bash curl -X POST http://localhost:8088/responses \ @@ -95,11 +123,7 @@ curl -X POST http://localhost:8088/responses \ -d '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "mcp_approval_response", "approval_request_id": "", "approve": false, "reason": "tone is too casual"}]}' ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "mcp_approval_response", "approval_request_id": "", "approve": false, "reason": "tone is too casual"}]}').Content -``` - -**Revise** — target the paired `function_call` item (its `call_id` is the same interrupt id) and send the feedback: +*Revise* — target the paired `function_call` item (its `call_id` is the same interrupt id) and send the feedback: ```bash curl -X POST http://localhost:8088/responses \ @@ -107,17 +131,54 @@ curl -X POST http://localhost:8088/responses \ -d '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "function_call_output", "call_id": "", "output": "{\"resume\": {\"feedback\": \"Shorter and more energetic, add a clear call to action.\"}}"}]}' ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"conversation": {"id": "demo-hitl-1"}, "input": [{"type": "function_call_output", "call_id": "", "output": "{\"resume\": {\"feedback\": \"Shorter and more energetic, add a clear call to action.\"}}"}]}').Content +The graph generates a new draft incorporating the feedback and pauses again with a fresh `mcp_approval_request` — repeat Step 2 until you approve or reject. + +### Deploy to Foundry + +Deploy the agent to Microsoft Foundry: + +```bash +azd deploy ``` -The graph generates a new draft incorporating the feedback and pauses again with a fresh `mcp_approval_request` — repeat Step 2 until you approve or reject. +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). + +### Invoke the deployed agent + +```bash +azd ai agent invoke "Draft a marketing email for our new AI product launch." +``` + +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt -### Test in Agent Inspector + # or pure pip + pip install -r requirements.txt + ``` -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Run and debug the agent -Type the following message in Inspector: +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Send the following message in the Inspector: ``` Draft a marketing email for our new AI product launch. @@ -125,21 +186,16 @@ Draft a marketing email for our new AI product launch. When the agent pauses with an approval request, the Inspector renders an interactive approval card. Approve, reject, or send revision feedback directly from there. -## Deploying the Agent to Foundry +### Or run manually, then open the Inspector -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. -### Deploying with the Foundry Toolkit VS Code Extension +### Deploy to Foundry -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. diff --git a/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/src/langgraph-human-in-the-loop-responses/main.py b/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/src/langgraph-human-in-the-loop-responses/main.py index a40d90783..6050f41a9 100644 --- a/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/src/langgraph-human-in-the-loop-responses/main.py +++ b/samples/python/hosted-agents/langgraph/responses/07-human-in-the-loop/src/langgraph-human-in-the-loop-responses/main.py @@ -73,6 +73,8 @@ def _build_chat_model() -> ChatOpenAI: model=deployment, base_url=str(openai_client.base_url), api_key=token_provider, + use_responses_api=True, + output_version="responses/v1", ) diff --git a/samples/python/hosted-agents/langgraph/responses/08-observability/README.md b/samples/python/hosted-agents/langgraph/responses/08-observability/README.md index 91a31afd4..6acd1238c 100644 --- a/samples/python/hosted-agents/langgraph/responses/08-observability/README.md +++ b/samples/python/hosted-agents/langgraph/responses/08-observability/README.md @@ -43,32 +43,66 @@ The sample sets two tracing toggles in [azure.yaml](azure.yaml): The `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable is injected when the agent is deployed to Foundry, so no extra setup is needed in hosted mode. To ship telemetry from a **local** run, you must set it yourself — either in `.env` (for `python main.py`) or via `azd env set` (for `azd ai agent run`). -## Running the Agent Host +## Option 1: Azure Developer CLI (`azd`) -Follow the instructions in the [Running the Agent Host Locally](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host. To ship telemetry from a local run, also set `APPLICATIONINSIGHTS_CONNECTION_STRING` — see [.env.example](src/langgraph-observability-responses/.env.example). +### Prerequisites -## Interacting with the agent +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +2. Install the Foundry extension: -> Depending on how you run the agent host, you can invoke the agent using `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the [parent README](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md) for more details. Use this README for sample queries you can send to the agent. + ```bash + azd ext install microsoft.foundry + ``` -Send a single-turn request that exercises both tools and produces a rich span tree: +3. Authenticate: + + ```bash + azd auth login + ``` + +### Initialize the agent project + +No cloning required. Create a new folder and initialize from the manifest: ```bash -curl -X POST http://localhost:8088/responses \ - -H "Content-Type: application/json" \ - -d '{"input": "What time is it right now, and what is 42 multiplied by 17?"}' +mkdir hosted-langgraph-agent && cd hosted-langgraph-agent +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/responses/08-observability/azure.yaml +``` + +Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. + +### Provision Azure resources (if needed) + +If you don't already have a Foundry project and model deployment: + +```bash +azd provision ``` -```powershell -(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "What time is it right now, and what is 42 multiplied by 17?"}').Content +### Run the agent locally + +```bash +azd ai agent run ``` -Invoke with `azd`: +The agent host will start on `http://localhost:8088`. To ship telemetry from a local run, also set `APPLICATIONINSIGHTS_CONNECTION_STRING` via `azd env set` — see [.env.example](src/langgraph-observability-responses/.env.example). -```powershell +### Invoke the local agent + +In a separate terminal, invoke the running agent. This single-turn request exercises both tools and produces a rich span tree: + +```bash azd ai agent invoke --local "What time is it right now, and what is 42 multiplied by 17?" ``` +Or invoke directly with curl: + +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "What time is it right now, and what is 42 multiplied by 17?"}' +``` + A typical span hierarchy for this request: - `invoke_agent` — the overall agent turn. @@ -77,35 +111,65 @@ A typical span hierarchy for this request: See the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for the span and attribute reference. -### Test in Agent Inspector - -Once the agent is running locally, open **Agent Inspector** in VS Code (Command Palette: **Foundry Toolkit: Open Agent Inspector**) to interactively send messages and view responses. +### Deploy to Foundry -Type the following message in Inspector: +Once tested locally, deploy to Microsoft Foundry: -``` -What time is it right now, and what is 42 multiplied by 17? +```bash +azd deploy ``` -## Deploying the Agent to Foundry +For the full deployment guide, see [Azure AI Foundry hosted agents](https://aka.ms/azdaiagent/docs). -To host the agent on Foundry, follow the instructions in the [Deploying the Agent to Foundry](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/README.md#deploying-the-agent-to-foundry) section of the README in the parent directory. +### Invoke the deployed agent -### Viewing telemetry in Foundry +```bash +azd ai agent invoke "What time is it right now, and what is 42 multiplied by 17?" +``` Once deployed, the agent's traces, metrics, and logs flow into the Application Insights workspace associated with your Foundry project. In the Foundry portal, open the agent and switch to the **Traces** tab to see each conversation and drill into its span tree. -### Deploying with the Foundry Toolkit VS Code Extension - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a tab-based **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate what it can. -2. If prompted, complete **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one) to deploy to. -3. On the **Basics** tab, configure the core deployment settings: - - **Deployment Method**: **Code** (upload as a ZIP) or **Container** (Docker image via ACR). - - For **Code**, pick a packaging option: **Remote** or **Local**. - - For **Container**, pick a registry option: default ACR, your own ACR, or a prebuilt ACR image. - - **Hosted Agent Name**: confirm the name to register with the hosting service. -4. On the **Review + Deploy** tab, finalize the runtime and resources: - - Confirm the auto-detected runtime details (language, entry point, or Dockerfile). - - Pick a **CPU and Memory** size. - - Click **Deploy**. Fields are validated inline, and the extension handles the build/upload, agent version creation, and RBAC role assignment. +## Option 2: VS Code (Foundry Toolkit) + +### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed. +2. For debugging Python in VS Code, install the **[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)** extension pack. + +### Set up the Python virtual environment + +- Open the Command Palette (`Ctrl+Shift+P`) and run **Python: Create Environment...** to create a virtual environment in the workspace (or **Python: Select Interpreter** to use an existing one). +- Ensure `pip` is version 26.1 or newer (check with `pip --version`). Older versions fail to resolve this sample's dependencies. Upgrade if needed: + + ```bash + python -m pip install --upgrade pip + ``` + +- Install dependencies in the virtual environment. One transitive dependency ships as a pre-release, so pre-releases must be allowed when using `uv`: + + ```bash + # use uv to accelerate + pip install uv + uv pip install --prerelease=allow -r requirements.txt + + # or pure pip + pip install -r requirements.txt + ``` + +### Run and debug the agent + +Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector. + +### Or run manually, then open the Inspector + +1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`). +2. Start the agent: `python main.py` (listens on `http://localhost:8088`). +3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test. + +### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. 5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab.