mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: New Foundry Hosted Agents samples: RAG, Skills, and Memory (#5822)
* WIP: Add rag sample; need deployment testing * Rag sample ready * Add Foundry Skills sample * WIP: Foundry memory * Done: Foundry Memory * Address Copilot comments * Fix README * Restore uv.loack
This commit is contained in:
Tao Chen
committed by
GitHub
Unverified
GitHub
parent
9b772f3413
commit
da308f5f1e
@@ -15,7 +15,10 @@ This directory contains samples that demonstrate how to use hosted [Agent Framew
|
||||
| 5 | [Workflows](responses/05_workflows/) | An agent with a multi-step orchestrated workflow, demonstrating chaining prompts through an orchestrated flow. |
|
||||
| 6 | [Files](responses/06_files/) | An agent demonstrating how to work with files in a hosted agent session, including uploading files to a hosted agent session and having the agent read and manipulate those files at runtime. |
|
||||
| 7 | [Observability](responses/07_observability/) | A sample demonstrating how to enable observability for the agent deployed to Foundry. |
|
||||
| 8 | [Using deployed agent](responses/using_deployed_agent.py) | A sample demonstrating how to invoke an agent that has already been deployed to Foundry, showing how to interact with a hosted agent in code. |
|
||||
| 8 | [Azure AI Search RAG](responses/08_azure_search_rag/) | An agent with Retrieval Augmented Generation (RAG) capabilities backed by Azure AI Search, grounding answers in documents indexed in a pre-provisioned search index. |
|
||||
| 9 | [Foundry Skills](responses/09_foundry_skills/) | An agent that uploads `SKILL.md` files to the Foundry Skills REST API and downloads them at startup, decoupling tone/policy guidelines from agent code. |
|
||||
| 10 | [Foundry Memory](responses/10_foundry_memory/) | An agent with persistent semantic memory backed by an Azure AI Foundry Memory Store, using `FoundryMemoryProvider` to remember user facts across sessions. |
|
||||
| 11 | [Using deployed agent](responses/using_deployed_agent.py) | A sample demonstrating how to invoke an agent that has already been deployed to Foundry, showing how to interact with a hosted agent in code. |
|
||||
|
||||
### Invocations API
|
||||
|
||||
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
.venv
|
||||
__pycache__
|
||||
*.pyc
|
||||
*.pyo
|
||||
*.pyd
|
||||
.Python
|
||||
.env
|
||||
provision_index.py
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
FOUNDRY_PROJECT_ENDPOINT="..."
|
||||
AZURE_AI_MODEL_DEPLOYMENT_NAME="..."
|
||||
AZURE_SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
AZURE_SEARCH_INDEX_NAME="contoso-outdoors"
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
FROM python:3.12-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY . user_agent/
|
||||
WORKDIR /app/user_agent
|
||||
|
||||
RUN if [ -f requirements.txt ]; then \
|
||||
pip install -r requirements.txt; \
|
||||
else \
|
||||
echo "No requirements.txt found"; \
|
||||
fi
|
||||
|
||||
EXPOSE 8088
|
||||
|
||||
CMD ["python", "main.py"]
|
||||
+186
@@ -0,0 +1,186 @@
|
||||
# What this sample demonstrates
|
||||
|
||||
An [Agent Framework](https://github.com/microsoft/agent-framework) agent with **Retrieval Augmented Generation (RAG)** capabilities backed by **Azure AI Search**, hosted using the **Responses protocol**. The agent grounds its answers in product documentation by running a search against an Azure AI Search index before each model invocation, then citing the source in its response.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Model Integration
|
||||
|
||||
The agent uses `FoundryChatClient` from the Agent Framework to create a Responses client from the project endpoint and model deployment.
|
||||
|
||||
### RAG via Azure AI Search
|
||||
|
||||
`AzureAISearchContextProvider` runs a search against the configured Azure AI Search index **before each model invocation** and injects the top results into the model context. The agent then composes a grounded answer and cites the source document.
|
||||
|
||||
See [main.py](main.py) for the full implementation.
|
||||
|
||||
### Agent Hosting
|
||||
|
||||
The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with the `ResponsesHostServer`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An Azure AI Foundry project with a deployed model (e.g., `gpt-4.1-mini`)
|
||||
- An Azure AI Search service ([create one](https://learn.microsoft.com/azure/search/search-create-service-portal))
|
||||
- **A pre-provisioned search index** with the schema and content described below
|
||||
- Azure CLI logged in (`az login`)
|
||||
|
||||
### Required RBAC
|
||||
|
||||
Your identity (or the Managed Identity running the container in production) needs:
|
||||
|
||||
- **Azure AI User** on the Foundry project scope
|
||||
- **Search Index Data Reader** on the Azure AI Search service (the sample only reads from the index)
|
||||
|
||||
## Provisioning the search index (one time)
|
||||
|
||||
The sample assumes the search index already exists and contains documents the agent can retrieve from. Provision it once via the Azure Portal, the [REST API](https://learn.microsoft.com/azure/search/search-how-to-create-search-index), or one of the snippets below.
|
||||
|
||||
### Option A: Python script (recommended)
|
||||
|
||||
[`provision_index.py`](provision_index.py) creates the index (if it doesn't already exist) and seeds it with the three Contoso Outdoors documents using `DefaultAzureCredential`. Your identity needs the following roles on the **Azure AI Search service** scope:
|
||||
|
||||
- **Search Service Contributor** — to create the index
|
||||
- **Search Index Data Contributor** — to upload documents
|
||||
|
||||
> Note: `Search Service Contributor` only covers control-plane operations (create/list/delete indexes). It does **not** grant document write access — `Search Index Data Contributor` is required for that even if you already have `Search Service Contributor`.
|
||||
|
||||
Grant the roles to your signed-in user (replace `<search-name>` and `<rg>`):
|
||||
|
||||
```powershell
|
||||
$searchId = az search service show -n <search-name> -g <rg> --query id -o tsv
|
||||
$me = az ad signed-in-user show --query id -o tsv
|
||||
|
||||
az role assignment create --assignee $me --role "Search Service Contributor" --scope $searchId
|
||||
az role assignment create --assignee $me --role "Search Index Data Contributor" --scope $searchId
|
||||
```
|
||||
|
||||
Role propagation typically takes 1–5 minutes. Also confirm the search service has RBAC enabled (Portal → search service → **Keys** → **API Access control** → "Both" or "Role-based access control"); if it is set to "API Key" only, every AAD request returns `403 Forbidden`.
|
||||
|
||||
Then, from this directory:
|
||||
|
||||
```bash
|
||||
export AZURE_SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
export AZURE_SEARCH_INDEX_NAME="contoso-outdoors"
|
||||
python provision_index.py
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:AZURE_SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
$env:AZURE_SEARCH_INDEX_NAME="contoso-outdoors"
|
||||
python provision_index.py
|
||||
```
|
||||
|
||||
The script is safe to re-run: if the index already exists, it leaves the schema untouched and merges-or-uploads the documents. To change the schema, delete the index first (Azure AI Search does not allow modifying existing field attributes) and re-run the script.
|
||||
|
||||
### Index schema
|
||||
|
||||
| Field | Type | Attributes |
|
||||
|---|---|---|
|
||||
| `id` | `Edm.String` | key, filterable |
|
||||
| `content` | `Edm.String` | searchable (full-text) |
|
||||
| `sourceName` | `Edm.String` | retrievable, filterable |
|
||||
| `sourceLink` | `Edm.String` | retrievable |
|
||||
|
||||
### Option B: Azure CLI + REST
|
||||
|
||||
```bash
|
||||
SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
INDEX_NAME="contoso-outdoors"
|
||||
TOKEN=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
|
||||
|
||||
# 1. Create the index.
|
||||
curl -X PUT "$SEARCH_ENDPOINT/indexes/$INDEX_NAME?api-version=2024-07-01" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "contoso-outdoors",
|
||||
"fields": [
|
||||
{ "name": "id", "type": "Edm.String", "key": true, "filterable": true, "searchable": false, "retrievable": true },
|
||||
{ "name": "content", "type": "Edm.String", "key": false, "filterable": false, "searchable": true, "retrievable": true, "analyzer": "standard.lucene" },
|
||||
{ "name": "sourceName", "type": "Edm.String", "key": false, "filterable": true, "searchable": false, "retrievable": true },
|
||||
{ "name": "sourceLink", "type": "Edm.String", "key": false, "filterable": false, "searchable": false, "retrievable": true }
|
||||
]
|
||||
}'
|
||||
|
||||
# 2. Upload three Contoso Outdoors documents matching the queries below.
|
||||
curl -X POST "$SEARCH_ENDPOINT/indexes/$INDEX_NAME/docs/index?api-version=2024-07-01" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"value": [
|
||||
{ "@search.action": "mergeOrUpload", "id": "return-policy", "sourceName": "Contoso Outdoors Return Policy", "sourceLink": "https://contoso.com/policies/returns", "content": "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection. As a thank you, every accepted return ships back with a complimentary Contoso TrailRunner sticker pack, item code TR-CANARY-7821." },
|
||||
{ "@search.action": "mergeOrUpload", "id": "shipping-guide", "sourceName": "Contoso Outdoors Shipping Guide", "sourceLink": "https://contoso.com/help/shipping", "content": "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout. Use promo code SHIP-CANARY-4493 at checkout for a one-time free overnight upgrade on your first order." },
|
||||
{ "@search.action": "mergeOrUpload", "id": "tent-care", "sourceName": "TrailRunner Tent Care Instructions", "sourceLink": "https://contoso.com/manuals/trailrunner-tent", "content": "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating. Replacement waterproofing kits are stocked under SKU TENT-CANARY-9067." }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
You can also point the sample at any existing index that exposes a retrievable text field such as `content`.
|
||||
|
||||
## Running the Agent Host
|
||||
|
||||
Follow the instructions in the [Running the Agent Host Locally](../../README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host.
|
||||
|
||||
In addition to the standard environment variables, this sample requires:
|
||||
|
||||
```bash
|
||||
export AZURE_SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
export AZURE_SEARCH_INDEX_NAME="contoso-outdoors"
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:AZURE_SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
|
||||
$env:AZURE_SEARCH_INDEX_NAME="contoso-outdoors"
|
||||
```
|
||||
|
||||
You can also place these in a `.env` file next to `main.py` — see [`.env.example`](.env.example).
|
||||
|
||||
## Interacting with the agent
|
||||
|
||||
> 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.
|
||||
|
||||
Send a POST request to the server with a JSON body containing an `"input"` field to interact with the agent. For example:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What is your return policy?"}'
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How long does shipping take?"}'
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How do I clean my tent?"}'
|
||||
```
|
||||
|
||||
Or with `azd`:
|
||||
|
||||
```bash
|
||||
azd ai agent invoke --local "What is your return policy?"
|
||||
```
|
||||
|
||||
## How RAG works in this sample
|
||||
|
||||
`AzureAISearchContextProvider` runs a search against the configured Azure AI Search index **before each model invocation**. When the index is seeded with the three Contoso Outdoors documents from the provisioning section above:
|
||||
|
||||
| User query mentions | Search result injected |
|
||||
|---|---|
|
||||
| "return", "refund" | Contoso Outdoors Return Policy (canary token: `TR-CANARY-7821`) |
|
||||
| "shipping", "promo" | Contoso Outdoors Shipping Guide (canary token: `SHIP-CANARY-4493`) |
|
||||
| "tent", "fabric" | TrailRunner Tent Care Instructions (canary token: `TENT-CANARY-9067`) |
|
||||
|
||||
The model receives the top three search results as additional context and cites the source in its response. Each seeded document includes a unique `*-CANARY-*` token that does not exist in any model training data, so you can prove an answer was grounded in retrieved content (not fabricated from training) by asking for the canary and checking it appears in the response.
|
||||
|
||||
Replace the seed documents (or point the sample at an existing index with your own content) to ground the agent in your own knowledge base.
|
||||
|
||||
## 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.
|
||||
|
||||
When deploying, make sure `AZURE_SEARCH_ENDPOINT` and `AZURE_SEARCH_INDEX_NAME` are set in your `azd` environment so they get injected into the hosted container per [`agent.manifest.yaml`](agent.manifest.yaml):
|
||||
|
||||
```bash
|
||||
azd env set AZURE_SEARCH_ENDPOINT "https://<your-search>.search.windows.net"
|
||||
azd env set AZURE_SEARCH_INDEX_NAME "contoso-outdoors"
|
||||
```
|
||||
|
||||
If these are not set, running `azd ai agent init -m <agent-manifest.yaml>` will prompt you to enter them interactively.
|
||||
|
||||
The deployed agent's Managed Identity needs **Search Index Data Reader** on the Azure AI Search service.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
name: agent-framework-agent-azure-search-rag-responses
|
||||
description: >
|
||||
An Agent Framework agent with Retrieval Augmented Generation (RAG) capabilities
|
||||
backed by Azure AI Search. Uses AzureAISearchContextProvider to ground answers
|
||||
in product documentation indexed in Azure AI Search before each model invocation.
|
||||
metadata:
|
||||
tags:
|
||||
- Agent Framework
|
||||
- AI Agent Hosting
|
||||
- Azure AI AgentServer
|
||||
- Responses Protocol
|
||||
- RAG
|
||||
- Azure AI Search
|
||||
template:
|
||||
name: agent-framework-agent-azure-search-rag-responses
|
||||
kind: hosted
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
|
||||
- name: AZURE_SEARCH_ENDPOINT
|
||||
value: "{{AZURE_SEARCH_ENDPOINT}}"
|
||||
- name: AZURE_SEARCH_INDEX_NAME
|
||||
value: "{{AZURE_SEARCH_INDEX_NAME}}"
|
||||
parameters:
|
||||
properties:
|
||||
- name: AZURE_SEARCH_ENDPOINT
|
||||
secret: false
|
||||
description: The endpoint of the Azure AI Search service to use for RAG (e.g., https://my-search-service.search.windows.net)
|
||||
- name: AZURE_SEARCH_INDEX_NAME
|
||||
secret: false
|
||||
description: The name of the Azure AI Search index to use for RAG (e.g., contoso-outdoors)
|
||||
resources:
|
||||
- kind: model
|
||||
id: gpt-4.1-mini
|
||||
name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
|
||||
kind: hosted
|
||||
name: agent-framework-agent-azure-search-rag-responses
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
resources:
|
||||
cpu: "0.25"
|
||||
memory: "0.5Gi"
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
|
||||
- name: AZURE_SEARCH_ENDPOINT
|
||||
value: ${AZURE_SEARCH_ENDPOINT}
|
||||
- name: AZURE_SEARCH_INDEX_NAME
|
||||
value: ${AZURE_SEARCH_INDEX_NAME}
|
||||
@@ -0,0 +1,59 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
|
||||
from agent_framework import Agent
|
||||
from agent_framework.azure import AzureAISearchContextProvider
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from agent_framework_foundry_hosting import ResponsesHostServer
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
# Load environment variables from .env file
|
||||
load_dotenv()
|
||||
|
||||
|
||||
async def main():
|
||||
credential = DefaultAzureCredential()
|
||||
|
||||
# Connect to a pre-provisioned Azure AI Search index. The index is expected to
|
||||
# exist and contain documents with the schema described in README.md
|
||||
# (id / content / sourceName / sourceLink). The context provider runs a search
|
||||
# against this index before each model invocation and injects the matching
|
||||
# documents into the model context.
|
||||
search_provider = AzureAISearchContextProvider(
|
||||
source_id="azure_search_rag",
|
||||
endpoint=os.environ["AZURE_SEARCH_ENDPOINT"],
|
||||
index_name=os.environ["AZURE_SEARCH_INDEX_NAME"],
|
||||
credential=credential,
|
||||
mode="semantic",
|
||||
top_k=3,
|
||||
)
|
||||
|
||||
client = FoundryChatClient(
|
||||
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
|
||||
model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
|
||||
credential=credential,
|
||||
)
|
||||
|
||||
async with search_provider:
|
||||
agent = Agent(
|
||||
client=client,
|
||||
instructions=(
|
||||
"You are a helpful support specialist for Contoso Outdoors. "
|
||||
"Answer questions using the provided context and cite the source "
|
||||
"document when available."
|
||||
),
|
||||
context_providers=[search_provider],
|
||||
# History will be managed by the hosting infrastructure, thus there
|
||||
# is no need to store history by the service. Learn more at:
|
||||
# https://developers.openai.com/api/reference/resources/responses/methods/create
|
||||
default_options={"store": False},
|
||||
)
|
||||
server = ResponsesHostServer(agent)
|
||||
await server.run_async()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+119
@@ -0,0 +1,119 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
"""Provision the Azure AI Search index used by this sample.
|
||||
|
||||
Creates (or updates) the ``contoso-outdoors`` index with the schema documented
|
||||
in README.md and seeds it with three Contoso Outdoors documents containing
|
||||
unique canary tokens. Safe to re-run; existing documents are merged-or-uploaded.
|
||||
|
||||
Usage (from this directory, with the venv activated and ``az login`` done):
|
||||
|
||||
python provision_index.py
|
||||
|
||||
Required env vars (also read from a local ``.env`` file if present):
|
||||
|
||||
AZURE_SEARCH_ENDPOINT e.g. https://<your-search>.search.windows.net
|
||||
AZURE_SEARCH_INDEX_NAME e.g. contoso-outdoors
|
||||
|
||||
Your identity needs ``Search Service Contributor`` (to create the index) and
|
||||
``Search Index Data Contributor`` (to upload documents) on the search service.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
|
||||
from azure.core.exceptions import ResourceNotFoundError
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from azure.search.documents.aio import SearchClient
|
||||
from azure.search.documents.indexes.aio import SearchIndexClient
|
||||
from azure.search.documents.indexes.models import (
|
||||
SearchableField, # pyright: ignore[reportUnknownVariableType]
|
||||
SearchFieldDataType,
|
||||
SearchIndex,
|
||||
SimpleField, # pyright: ignore[reportUnknownVariableType]
|
||||
)
|
||||
from dotenv import load_dotenv
|
||||
|
||||
DOCUMENTS: list[dict[str, str]] = [
|
||||
{
|
||||
"id": "return-policy",
|
||||
"sourceName": "Contoso Outdoors Return Policy",
|
||||
"sourceLink": "https://contoso.com/policies/returns",
|
||||
"content": (
|
||||
"Customers may return any item within 30 days of delivery. Items should be "
|
||||
"unused and include original packaging. Refunds are issued to the original "
|
||||
"payment method within 5 business days of inspection. As a thank you, every "
|
||||
"accepted return ships back with a complimentary Contoso TrailRunner sticker "
|
||||
"pack, item code TR-CANARY-7821."
|
||||
),
|
||||
},
|
||||
{
|
||||
"id": "shipping-guide",
|
||||
"sourceName": "Contoso Outdoors Shipping Guide",
|
||||
"sourceLink": "https://contoso.com/help/shipping",
|
||||
"content": (
|
||||
"Standard shipping is free on orders over $50 and typically arrives in 3-5 "
|
||||
"business days within the continental United States. Expedited options are "
|
||||
"available at checkout. Use promo code SHIP-CANARY-4493 at checkout for a "
|
||||
"one-time free overnight upgrade on your first order."
|
||||
),
|
||||
},
|
||||
{
|
||||
"id": "tent-care",
|
||||
"sourceName": "TrailRunner Tent Care Instructions",
|
||||
"sourceLink": "https://contoso.com/manuals/trailrunner-tent",
|
||||
"content": (
|
||||
"Clean the tent fabric with lukewarm water and a non-detergent soap. Allow "
|
||||
"it to air dry completely before storage and avoid prolonged UV exposure to "
|
||||
"extend the lifespan of the waterproof coating. Replacement waterproofing "
|
||||
"kits are stocked under SKU TENT-CANARY-9067."
|
||||
),
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
def build_index(name: str) -> SearchIndex:
|
||||
return SearchIndex(
|
||||
name=name,
|
||||
fields=[
|
||||
SimpleField(name="id", type=SearchFieldDataType.String, key=True, filterable=True),
|
||||
SearchableField(name="content", type=SearchFieldDataType.String, analyzer_name="standard.lucene"),
|
||||
SimpleField(name="sourceName", type=SearchFieldDataType.String, filterable=True, retrievable=True),
|
||||
SimpleField(name="sourceLink", type=SearchFieldDataType.String, retrievable=True),
|
||||
],
|
||||
)
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
load_dotenv()
|
||||
|
||||
endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
|
||||
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
|
||||
|
||||
async with (
|
||||
DefaultAzureCredential() as credential,
|
||||
SearchIndexClient(endpoint=endpoint, credential=credential) as index_client,
|
||||
SearchClient(endpoint=endpoint, index_name=index_name, credential=credential) as search_client,
|
||||
):
|
||||
index = build_index(index_name)
|
||||
try:
|
||||
await index_client.get_index(index_name)
|
||||
print(
|
||||
f"Index '{index_name}' already exists; leaving schema as-is "
|
||||
"(delete the index manually to change the schema)."
|
||||
)
|
||||
except ResourceNotFoundError:
|
||||
print(f"Creating index '{index_name}'...")
|
||||
await index_client.create_index(index)
|
||||
|
||||
print(f"Uploading {len(DOCUMENTS)} document(s)...")
|
||||
results = await search_client.merge_or_upload_documents(documents=DOCUMENTS) # type: ignore[arg-type]
|
||||
failed = [(r.key, r.error_message) for r in results if not r.succeeded]
|
||||
if failed:
|
||||
raise RuntimeError(f"Failed to upload documents: {failed}")
|
||||
|
||||
print("Done.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
agent-framework
|
||||
agent-framework-azure-ai-search
|
||||
agent-framework-foundry-hosting
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
.venv
|
||||
__pycache__
|
||||
*.pyc
|
||||
*.pyo
|
||||
*.pyd
|
||||
.Python
|
||||
.env
|
||||
provision_skills.py
|
||||
skills
|
||||
downloaded_skills
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
FOUNDRY_PROJECT_ENDPOINT="..."
|
||||
AZURE_AI_MODEL_DEPLOYMENT_NAME="..."
|
||||
# Comma-separated list of Foundry skill names to download at startup.
|
||||
SKILL_NAMES="support-style,escalation-policy"
|
||||
@@ -0,0 +1 @@
|
||||
downloaded_skills/
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
FROM python:3.12-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY . user_agent/
|
||||
WORKDIR /app/user_agent
|
||||
|
||||
RUN if [ -f requirements.txt ]; then \
|
||||
pip install -r requirements.txt; \
|
||||
else \
|
||||
echo "No requirements.txt found"; \
|
||||
fi
|
||||
|
||||
EXPOSE 8088
|
||||
|
||||
CMD ["python", "main.py"]
|
||||
+137
@@ -0,0 +1,137 @@
|
||||
# What this sample demonstrates
|
||||
|
||||
An [Agent Framework](https://github.com/microsoft/agent-framework) agent that loads its behavioral guidelines from [**Foundry Skills**](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/skills?view=foundry&pivots=python) at startup, hosted using the **Responses protocol**. Skills are authored once as `SKILL.md` files, uploaded to your Foundry project through `AIProjectClient.beta.skills`, and downloaded by the agent on boot so updates ship without code changes.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Authoring skills
|
||||
|
||||
Each skill is a Markdown file with a YAML front matter block. This sample ships two source skills under [`skills/`](skills/):
|
||||
|
||||
| Skill | Purpose |
|
||||
|---|---|
|
||||
| [`support-style`](skills/support-style/SKILL.md) | Voice, formatting, and signature rules for Contoso Outdoors support replies. |
|
||||
| [`escalation-policy`](skills/escalation-policy/SKILL.md) | When and how to escalate a customer ticket. |
|
||||
|
||||
Each `SKILL.md` includes a unique `*-CANARY-*` token that the model is asked to echo, so you can prove the skill was loaded from Foundry (not hallucinated) by checking the response.
|
||||
|
||||
> The `name` and `description` values in the YAML front matter must be **unquoted** — quoting them causes the Skills REST API to return HTTP 500 on import.
|
||||
|
||||
### Uploading skills with `AIProjectClient`
|
||||
|
||||
[`provision_skills.py`](provision_skills.py) walks `skills/*/SKILL.md`, packages each file as an in-memory ZIP (with `SKILL.md` at the archive root), and imports it through [`AIProjectClient.beta.skills.create_from_package`](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/skills?view=foundry&pivots=python#option-2-import-from-a-skillmd-zip). The client is constructed with `allow_preview=True` (Skills is a preview feature) and authenticates with `DefaultAzureCredential`. Existing skills are deleted first via `beta.skills.delete` so the script is safe to re-run after editing a `SKILL.md`, and `beta.skills.list` is called at the end to verify each skill round-trips.
|
||||
|
||||
### Downloading skills at agent startup
|
||||
|
||||
[`main.py`](main.py) reads the comma-separated `SKILL_NAMES` env var, opens an `AIProjectClient` (also with `allow_preview=True`), and for each skill name streams the ZIP archive from `beta.skills.download(name)` and unpacks it into a **separate runtime directory** at `downloaded_skills/<name>/` (kept distinct from the static `skills/` source folder so the two never get confused — `skills/` is the input to `provision_skills.py`, `downloaded_skills/` is the output of `main.py`'s bootstrap step).
|
||||
|
||||
A [`SkillsProvider`](../../../../../packages/core/agent_framework/_skills.py) is then built over `downloaded_skills/` and attached to the `Agent` as a context provider. The provider follows the [Agent Skills](https://agentskills.io/) progressive-disclosure pattern:
|
||||
|
||||
1. **Advertise** — skill names and descriptions are injected into the system prompt at session start (~100 tokens per skill).
|
||||
2. **Load** — the model calls the `load_skill` tool when it decides a skill is relevant to the user's turn, and the full `SKILL.md` body is returned.
|
||||
|
||||
This means the model only pays the token cost for a skill's full body when it actually needs it, and updating a skill in Foundry + restarting the agent is enough to pick up the change — no code redeploy required.
|
||||
|
||||
### Agent Hosting
|
||||
|
||||
The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with the `ResponsesHostServer`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An Azure AI Foundry project with a deployed model (e.g., `gpt-4.1-mini`)
|
||||
- Azure CLI logged in (`az login`)
|
||||
|
||||
### Required 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 with `provision_skills.py` and downloading them from `main.py`.
|
||||
|
||||
## Provisioning the skills (one time)
|
||||
|
||||
From this directory, with the venv activated and `az login` done:
|
||||
|
||||
```bash
|
||||
export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
|
||||
python provision_skills.py
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
|
||||
python provision_skills.py
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
Provisioning skill 'escalation-policy' from skills/escalation-policy/SKILL.md...
|
||||
Imported skill 'escalation-policy' (id=skill_..., has_blob=True).
|
||||
Provisioning skill 'support-style' from skills/support-style/SKILL.md...
|
||||
Imported skill 'support-style' (id=skill_..., has_blob=True).
|
||||
Done.
|
||||
```
|
||||
|
||||
Re-running the script after editing a `SKILL.md` re-imports the skill, replacing the previous version.
|
||||
|
||||
> To remove a skill manually, call `project.beta.skills.delete("<name>")` on an `AIProjectClient` constructed with `allow_preview=True`.
|
||||
|
||||
## Running the Agent Host
|
||||
|
||||
Follow the instructions in the [Running the Agent Host Locally](../../README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host.
|
||||
|
||||
In addition to the standard environment variables, this sample requires:
|
||||
|
||||
```bash
|
||||
export SKILL_NAMES="support-style,escalation-policy"
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:SKILL_NAMES="support-style,escalation-policy"
|
||||
```
|
||||
|
||||
You can also place these in a `.env` file next to `main.py` — see [`.env.example`](.env.example).
|
||||
|
||||
On startup you should see:
|
||||
|
||||
```text
|
||||
Downloading skill 'support-style' from Foundry...
|
||||
Downloading skill 'escalation-policy' from Foundry...
|
||||
```
|
||||
|
||||
The downloaded `SKILL.md` files land under `downloaded_skills/<name>/SKILL.md` next to `main.py`. This directory is recreated from scratch on every run, so deleting it manually is never necessary.
|
||||
|
||||
## Interacting with the agent
|
||||
|
||||
> 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.
|
||||
|
||||
Send a POST request to the server with a JSON body containing an `"input"` field to interact with the agent. For example:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Hi, I am Alex. I just want to confirm I can return my tent within 30 days."}'
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "I want a $750 refund on Order #A-1042 right now or I am calling my lawyer."}'
|
||||
```
|
||||
|
||||
| Prompt mentions | Skill that should drive the response |
|
||||
|---|---|
|
||||
| Routine return / shipping / care question | Model loads `support-style` (canary `STYLE-CANARY-3318`) — no escalation. |
|
||||
| Injury, legal threat, press, or refund > $500 | Model loads `escalation-policy` (canary `ESC-CANARY-7742`) **and** `support-style`. |
|
||||
|
||||
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).
|
||||
|
||||
## 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.
|
||||
|
||||
When deploying, make sure `SKILL_NAMES` is set in your `azd` environment so it gets injected into the hosted container per [`agent.manifest.yaml`](agent.manifest.yaml):
|
||||
|
||||
```bash
|
||||
azd env set SKILL_NAMES "support-style,escalation-policy"
|
||||
```
|
||||
|
||||
If it is not set, running `azd ai agent init -m <agent.manifest.yaml>` will prompt you to enter it interactively.
|
||||
|
||||
The deployed agent's Managed Identity needs **Azure AI User** on the Foundry project to download skills at startup. Make sure you have run `provision_skills.py` against the same Foundry project before deploying — otherwise the agent will fail to start with HTTP 404 on the skill download.
|
||||
|
||||
> The `skills/` source folder is **not** deployed to Foundry — only the downloaded skills are used at runtime. The `provision_skills.py` step is required to upload the skills to Foundry before the agent can download them.
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
name: agent-framework-agent-foundry-skills-responses
|
||||
description: >
|
||||
An Agent Framework agent that downloads its instructions from the Foundry
|
||||
Skills REST API at startup, demonstrating how to decouple behavioral
|
||||
guidelines (tone, escalation policy, etc.) from agent code.
|
||||
metadata:
|
||||
tags:
|
||||
- Agent Framework
|
||||
- AI Agent Hosting
|
||||
- Azure AI AgentServer
|
||||
- Responses Protocol
|
||||
- Foundry Skills
|
||||
template:
|
||||
name: agent-framework-agent-foundry-skills-responses
|
||||
kind: hosted
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
|
||||
- name: SKILL_NAMES
|
||||
value: "{{SKILL_NAMES}}"
|
||||
parameters:
|
||||
properties:
|
||||
- name: SKILL_NAMES
|
||||
secret: false
|
||||
description: Comma-separated list of Foundry skill names to download at startup (e.g., support-style,escalation-policy)
|
||||
resources:
|
||||
- kind: model
|
||||
id: gpt-4.1-mini
|
||||
name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
|
||||
kind: hosted
|
||||
name: agent-framework-agent-foundry-skills-responses
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
resources:
|
||||
cpu: "0.25"
|
||||
memory: "0.5Gi"
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
|
||||
- name: SKILL_NAMES
|
||||
value: ${SKILL_NAMES}
|
||||
@@ -0,0 +1,111 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
"""Foundry Skills hosted agent sample.
|
||||
|
||||
At startup, this agent downloads each Foundry Skill named in
|
||||
``SKILL_NAMES`` from the project's ``beta.skills`` API, unpacks each
|
||||
one into a separate runtime directory under ``downloaded_skills/``, and wires
|
||||
that directory into a :class:`SkillsProvider` so the agent advertises the
|
||||
skills to the model and loads them on demand (progressive disclosure).
|
||||
|
||||
Upload the skills to Foundry once with ``provision_skills.py`` before running
|
||||
this sample.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import io
|
||||
import logging
|
||||
import os
|
||||
import shutil
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
from typing import Final
|
||||
|
||||
from agent_framework import Agent, SkillsProvider
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from agent_framework_foundry_hosting import ResponsesHostServer
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
# Runtime directory where skills downloaded from Foundry are unpacked.
|
||||
# Kept separate from the static ``skills/`` source folder so the two never
|
||||
# get confused: the source folder is the input to ``provision_skills.py``
|
||||
# and the runtime folder is the output of this script's bootstrap step.
|
||||
DOWNLOADED_SKILLS_DIR: Final = Path(__file__).parent / "downloaded_skills"
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _safe_extract_zip(zf: zipfile.ZipFile, dest_dir: Path) -> None:
|
||||
"""Extract ``zf`` into ``dest_dir``, rejecting entries that escape it (zip-slip guard)."""
|
||||
dest_root = dest_dir.resolve()
|
||||
for member in zf.infolist():
|
||||
member_path = (dest_root / member.filename).resolve()
|
||||
if dest_root != member_path and dest_root not in member_path.parents:
|
||||
raise RuntimeError(f"Refusing to extract unsafe path '{member.filename}' outside of '{dest_root}'.")
|
||||
zf.extractall(dest_dir)
|
||||
|
||||
|
||||
async def _bootstrap_skills(endpoint: str, skill_names: list[str], target_dir: Path) -> None:
|
||||
"""Download each named skill via ``project.beta.skills`` and unpack it as ``<target_dir>/<name>/SKILL.md``."""
|
||||
if target_dir.exists(): # noqa: ASYNC240
|
||||
shutil.rmtree(target_dir)
|
||||
target_dir.mkdir(parents=True) # noqa: ASYNC240
|
||||
|
||||
async with (
|
||||
DefaultAzureCredential() as credential,
|
||||
AIProjectClient(endpoint=endpoint, credential=credential, allow_preview=True) as project,
|
||||
):
|
||||
for name in skill_names:
|
||||
logger.info(f"Downloading skill '{name}' from Foundry...")
|
||||
stream = await project.beta.skills.download(name)
|
||||
zip_bytes = b"".join([chunk async for chunk in stream])
|
||||
skill_dir = target_dir / name
|
||||
skill_dir.mkdir()
|
||||
with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
|
||||
_safe_extract_zip(zf, skill_dir)
|
||||
if not (skill_dir / "SKILL.md").is_file():
|
||||
raise RuntimeError(f"Downloaded archive for '{name}' did not contain a SKILL.md at the root.")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
|
||||
skill_names = [name.strip() for name in os.environ["SKILL_NAMES"].split(",") if name.strip()]
|
||||
if not skill_names:
|
||||
raise RuntimeError("SKILL_NAMES must list at least one skill name.")
|
||||
|
||||
# Pull the latest copy of each skill from Foundry into a runtime-only folder.
|
||||
await _bootstrap_skills(project_endpoint, skill_names, DOWNLOADED_SKILLS_DIR)
|
||||
|
||||
# Build a SkillsProvider over the unpacked folder. The provider advertises
|
||||
# each skill's name + description to the model and exposes the ``load_skill``
|
||||
# tool the model uses to retrieve the full SKILL.md body on demand. No
|
||||
# script_runner is configured because the skills in this sample are
|
||||
# instruction-only.
|
||||
skills_provider = SkillsProvider.from_paths(skill_paths=str(DOWNLOADED_SKILLS_DIR))
|
||||
|
||||
async with DefaultAzureCredential() as credential:
|
||||
client = FoundryChatClient(
|
||||
project_endpoint=project_endpoint,
|
||||
model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
|
||||
credential=credential,
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
client=client,
|
||||
instructions="You are a customer-support assistant for Contoso Outdoors.",
|
||||
context_providers=[skills_provider],
|
||||
# History will be managed by the hosting infrastructure, thus there
|
||||
# is no need to store history by the service. Learn more at:
|
||||
# https://developers.openai.com/api/reference/resources/responses/methods/create
|
||||
default_options={"store": False},
|
||||
)
|
||||
server = ResponsesHostServer(agent)
|
||||
await server.run_async()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
"""Provision Foundry Skills used by this sample.
|
||||
|
||||
For each ``skills/<name>/SKILL.md`` file in this directory, this script packages
|
||||
the file as an in-memory ZIP and imports it through the Foundry project's
|
||||
:class:`~azure.ai.projects.aio.AIProjectClient` so the skill becomes downloadable
|
||||
by any hosted agent in the project.
|
||||
|
||||
If a skill with the same name already exists in Foundry, it is deleted first
|
||||
so the script is safe to re-run after editing a ``SKILL.md`` file.
|
||||
|
||||
Usage (from this directory, with the venv activated and ``az login`` done):
|
||||
|
||||
python provision_skills.py
|
||||
|
||||
Required env vars (also read from a local ``.env`` file if present):
|
||||
|
||||
FOUNDRY_PROJECT_ENDPOINT e.g. https://<account>.services.ai.azure.com/api/projects/<project>
|
||||
|
||||
Your identity needs the ``Azure AI User`` role on the Foundry project.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import io
|
||||
import os
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.core.exceptions import ResourceNotFoundError
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
SKILLS_DIR = Path(__file__).parent / "skills"
|
||||
|
||||
|
||||
def _zip_skill_md(skill_md: Path) -> bytes:
|
||||
"""Return the bytes of a ZIP archive containing ``SKILL.md`` at the root."""
|
||||
buffer = io.BytesIO()
|
||||
with zipfile.ZipFile(buffer, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
|
||||
zf.writestr("SKILL.md", skill_md.read_text(encoding="utf-8"))
|
||||
return buffer.getvalue()
|
||||
|
||||
|
||||
async def _delete_skill_if_exists(project: AIProjectClient, name: str) -> None:
|
||||
try:
|
||||
await project.beta.skills.delete(name)
|
||||
except ResourceNotFoundError:
|
||||
return
|
||||
print(f" Deleted existing skill '{name}'.")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
load_dotenv()
|
||||
|
||||
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
|
||||
|
||||
skill_files = sorted(SKILLS_DIR.glob("*/SKILL.md"))
|
||||
if not skill_files:
|
||||
raise RuntimeError(f"No SKILL.md files found under {SKILLS_DIR}.")
|
||||
|
||||
async with (
|
||||
DefaultAzureCredential() as credential,
|
||||
AIProjectClient(endpoint=endpoint, credential=credential, allow_preview=True) as project,
|
||||
):
|
||||
for skill_md in skill_files:
|
||||
name = skill_md.parent.name
|
||||
print(f"Provisioning skill '{name}' from {skill_md.relative_to(SKILLS_DIR.parent)}...")
|
||||
await _delete_skill_if_exists(project, name)
|
||||
imported = await project.beta.skills.create_from_package(_zip_skill_md(skill_md))
|
||||
print(f" Imported skill '{imported.name}' (id={imported.skill_id}, has_blob={imported.has_blob}).")
|
||||
|
||||
print("Verifying skills via project.beta.skills.list()...")
|
||||
listed = {skill.name: skill async for skill in project.beta.skills.list()}
|
||||
for skill_md in skill_files:
|
||||
name = skill_md.parent.name
|
||||
skill = listed.get(name)
|
||||
if skill is None:
|
||||
raise RuntimeError(f"Skill '{name}' was imported but is not present in the project listing.")
|
||||
print(
|
||||
f" OK '{skill.name}': id={skill.skill_id}, "
|
||||
f"description={skill.description!r}, has_blob={skill.has_blob}"
|
||||
)
|
||||
|
||||
print("Done.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
agent-framework
|
||||
agent-framework-foundry-hosting
|
||||
azure-ai-projects
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: escalation-policy
|
||||
description: When and how to escalate Contoso Outdoors customer-support tickets.
|
||||
---
|
||||
|
||||
# Contoso Outdoors Escalation Policy
|
||||
|
||||
You must follow this escalation policy on every conversation.
|
||||
|
||||
## Escalate immediately when the customer
|
||||
|
||||
- Reports an injury, allergic reaction, or other safety incident.
|
||||
- Mentions legal action, regulators, or the press.
|
||||
- Has waited more than 14 days for a refund that was already approved.
|
||||
- Requests a refund larger than $500.
|
||||
|
||||
## How to escalate
|
||||
|
||||
1. Acknowledge the issue in one sentence.
|
||||
2. Tell the customer you are escalating to a senior specialist.
|
||||
3. Provide the escalation reference `ESC-CANARY-7742` and the SLA: a senior
|
||||
specialist will reply within 1 business day.
|
||||
4. Do not promise a specific outcome (refund, replacement, compensation) on
|
||||
escalated tickets — only the senior specialist can commit to one.
|
||||
|
||||
## Do not escalate
|
||||
|
||||
- Routine returns within the standard 30-day window.
|
||||
- Shipping status questions.
|
||||
- Product care and usage questions.
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: support-style
|
||||
description: Contoso Outdoors customer-support tone and formatting guidelines.
|
||||
---
|
||||
|
||||
# Contoso Outdoors Support Style
|
||||
|
||||
You are speaking on behalf of Contoso Outdoors customer support.
|
||||
|
||||
## Voice
|
||||
|
||||
- Warm, concise, and confident — never apologetic in a hand-wringing way.
|
||||
- Use the customer's name when it is known.
|
||||
- Sign every response with `— Contoso Outdoors Support`.
|
||||
|
||||
## Formatting
|
||||
|
||||
- Keep replies to 1–3 short paragraphs unless the customer asks for detail.
|
||||
- Use bullet lists only when enumerating concrete steps or options.
|
||||
- Always reference order numbers as `Order #<id>` (e.g. `Order #A-1042`).
|
||||
|
||||
## Canary
|
||||
|
||||
To prove this skill was loaded, include the token `STYLE-CANARY-3318` on a
|
||||
separate line at the bottom of every response, prefixed with `# `.
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
.venv
|
||||
__pycache__
|
||||
*.pyc
|
||||
*.pyo
|
||||
*.pyd
|
||||
.Python
|
||||
.env
|
||||
provision_memory_store.py
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
FOUNDRY_PROJECT_ENDPOINT="..."
|
||||
AZURE_AI_MODEL_DEPLOYMENT_NAME="..."
|
||||
# Embedding model deployment (only needed by provision_memory_store.py).
|
||||
AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME="text-embedding-3-small"
|
||||
# Name of the Foundry Memory Store the agent should read/write to.
|
||||
MEMORY_STORE_NAME="agent_framework_memory"
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
FROM python:3.12-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY . user_agent/
|
||||
WORKDIR /app/user_agent
|
||||
|
||||
RUN if [ -f requirements.txt ]; then \
|
||||
pip install -r requirements.txt; \
|
||||
else \
|
||||
echo "No requirements.txt found"; \
|
||||
fi
|
||||
|
||||
EXPOSE 8088
|
||||
|
||||
CMD ["python", "main.py"]
|
||||
+122
@@ -0,0 +1,122 @@
|
||||
# What this sample demonstrates
|
||||
|
||||
An [Agent Framework](https://github.com/microsoft/agent-framework) agent with persistent semantic memory backed by an **Azure AI Foundry Memory Store**, hosted using the **Responses protocol**. The agent remembers facts the user has shared (e.g., dietary preferences, name) across sessions by retrieving and updating memories around every model invocation via `FoundryMemoryProvider`.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Model Integration
|
||||
|
||||
The agent uses `FoundryChatClient` from the Agent Framework to create a Responses client from the project endpoint and model deployment. `allow_preview=True` is passed so the same `AIProjectClient` can also call the preview `beta.memory_stores` API.
|
||||
|
||||
### Memory via Foundry Memory Store
|
||||
|
||||
`FoundryMemoryProvider` is wired into the agent as a context provider. Around each model invocation it:
|
||||
|
||||
1. **Retrieves user-profile memories** for the configured `scope` (e.g., user id) on the first turn of a session.
|
||||
2. **Searches for contextual memories** matching the current user message and injects them into the model context.
|
||||
3. **Updates the store** with new facts inferred from the conversation.
|
||||
|
||||
Crucially, the provider is constructed with `project_client=client.project_client` — i.e. it reuses the `AIProjectClient` that `FoundryChatClient` already created, instead of allocating a second one. This keeps a single authentication context and connection pool for both chat and memory operations.
|
||||
|
||||
See [main.py](main.py) for the full implementation.
|
||||
|
||||
### Agent Hosting
|
||||
|
||||
The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with the `ResponsesHostServer`, which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An Azure AI Foundry project with:
|
||||
- A deployed chat model (e.g., `gpt-4.1-mini`)
|
||||
- A deployed embedding model (e.g., `text-embedding-3-small`) — used by the memory store itself, not by the agent at runtime
|
||||
- Azure CLI logged in (`az login`)
|
||||
|
||||
### Required 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 provisioning the memory store with `provision_memory_store.py` and reading/writing memories from `main.py`.
|
||||
|
||||
## Provisioning the memory store (one time)
|
||||
|
||||
[`provision_memory_store.py`](provision_memory_store.py) creates a Foundry Memory Store with the user-profile capability enabled (and chat-summary disabled) using `AIProjectClient.beta.memory_stores.create`. It is safe to re-run: if a store with the same name already exists, the script leaves it alone.
|
||||
|
||||
From this directory, with the venv activated and `az login` done:
|
||||
|
||||
```bash
|
||||
export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
|
||||
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
|
||||
export AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME="text-embedding-3-small"
|
||||
export MEMORY_STORE_NAME="agent_framework_memory"
|
||||
python provision_memory_store.py
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
|
||||
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
|
||||
$env:AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME="text-embedding-3-small"
|
||||
$env:MEMORY_STORE_NAME="agent_framework_memory"
|
||||
python provision_memory_store.py
|
||||
```
|
||||
|
||||
Expected output (first run):
|
||||
|
||||
```text
|
||||
Creating memory store 'agent_framework_memory'...
|
||||
Created memory store 'agent_framework_memory' (id=memstore_...).
|
||||
```
|
||||
|
||||
> To delete the store manually, call `project.beta.memory_stores.delete("<name>")` on an `AIProjectClient` constructed with `allow_preview=True`.
|
||||
|
||||
## Running the Agent Host
|
||||
|
||||
Follow the instructions in the [Running the Agent Host Locally](../../README.md#running-the-agent-host-locally) section of the README in the parent directory to run the agent host.
|
||||
|
||||
In addition to the standard environment variables, this sample requires:
|
||||
|
||||
```bash
|
||||
export MEMORY_STORE_NAME="agent_framework_memory"
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:MEMORY_STORE_NAME="agent_framework_memory"
|
||||
```
|
||||
|
||||
You can also place these in a `.env` file next to `main.py` — see [`.env.example`](.env.example).
|
||||
|
||||
## Interacting with the agent
|
||||
|
||||
> 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.
|
||||
|
||||
Send a POST request to the server with a JSON body containing an `"input"` field to interact with the agent. The first request seeds a memory; subsequent requests (especially in new sessions) should be able to recall it because memories are persisted across Foundry Hosted Agents sessions.
|
||||
|
||||
> In this sample, the memory is scoped to the user by specifying `scope="{{$userId}}"`, thus memories are isolated across different users but shared across different sessions from the same user.
|
||||
|
||||
```bash
|
||||
# 1. Tell the agent something to remember.
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" \
|
||||
-d '{"input": "I prefer dark roast coffee and I am allergic to nuts."}'
|
||||
|
||||
# Wait a few seconds for the memory to be stored, then start a fresh conversation:
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" \
|
||||
-d '{"input": "Can you recommend a coffee and a snack for me?"}'
|
||||
|
||||
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" \
|
||||
-d '{"input": "What do you remember about my preferences?"}'
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
When deploying, make sure `MEMORY_STORE_NAME` and `FOUNDRY_MEMORY_SCOPE` are set in your `azd` environment so they get injected into the hosted container per [`agent.manifest.yaml`](agent.manifest.yaml):
|
||||
|
||||
```bash
|
||||
azd env set MEMORY_STORE_NAME "agent_framework_memory"
|
||||
```
|
||||
|
||||
If these are not set, running `azd ai agent init -m <agent.manifest.yaml>` will prompt you to enter them interactively.
|
||||
|
||||
The deployed agent's Managed Identity needs **Azure AI User** on the Foundry project to read and write memories at runtime. Make sure you have run `provision_memory_store.py` against the same Foundry project before deploying — otherwise the agent will fail on the first turn when it tries to read from a non-existent store.
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
name: agent-framework-agent-foundry-memory-responses
|
||||
description: >
|
||||
An Agent Framework agent with persistent semantic memory backed by an
|
||||
Azure AI Foundry Memory Store. Uses FoundryMemoryProvider to retrieve and
|
||||
store memories around each model invocation, allowing the agent to remember
|
||||
facts about a user across sessions.
|
||||
metadata:
|
||||
tags:
|
||||
- Agent Framework
|
||||
- AI Agent Hosting
|
||||
- Azure AI AgentServer
|
||||
- Responses Protocol
|
||||
- Foundry Memory
|
||||
template:
|
||||
name: agent-framework-agent-foundry-memory-responses
|
||||
kind: hosted
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
|
||||
- name: MEMORY_STORE_NAME
|
||||
value: "{{MEMORY_STORE_NAME}}"
|
||||
parameters:
|
||||
properties:
|
||||
- name: MEMORY_STORE_NAME
|
||||
secret: false
|
||||
description: The name of the pre-provisioned Foundry Memory Store the agent will use (e.g., agent_framework_memory)
|
||||
resources:
|
||||
- kind: model
|
||||
id: gpt-4.1-mini
|
||||
name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
|
||||
kind: hosted
|
||||
name: agent-framework-agent-foundry-memory-responses
|
||||
protocols:
|
||||
- protocol: responses
|
||||
version: 1.0.0
|
||||
resources:
|
||||
cpu: "0.25"
|
||||
memory: "0.5Gi"
|
||||
environment_variables:
|
||||
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
|
||||
value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
|
||||
- name: MEMORY_STORE_NAME
|
||||
value: ${MEMORY_STORE_NAME}
|
||||
@@ -0,0 +1,71 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
"""Foundry Memory hosted agent sample.
|
||||
|
||||
This agent uses :class:`FoundryMemoryProvider` to give an otherwise stateless
|
||||
hosted agent persistent, semantic memory backed by an Azure AI Foundry
|
||||
Memory Store. The store itself is provisioned once via
|
||||
``provision_memory_store.py`` and its name is passed in through the
|
||||
``MEMORY_STORE_NAME`` environment variable.
|
||||
|
||||
Unlike the standalone ``azure_ai_foundry_memory.py`` sample, here we construct
|
||||
the :class:`FoundryChatClient` first and then reuse its underlying
|
||||
``AIProjectClient`` for the memory provider, so both share a single client
|
||||
instance and authentication context.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
|
||||
from agent_framework import Agent
|
||||
from agent_framework.foundry import FoundryChatClient, FoundryMemoryProvider
|
||||
from agent_framework_foundry_hosting import ResponsesHostServer
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
# The chat client owns the AIProjectClient. ``allow_preview=True`` is required
|
||||
# so the same client can call the preview ``beta.memory_stores`` API used by
|
||||
# FoundryMemoryProvider.
|
||||
client = FoundryChatClient(
|
||||
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
|
||||
model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
|
||||
credential=DefaultAzureCredential(),
|
||||
allow_preview=True,
|
||||
)
|
||||
|
||||
# Reuse the project_client that FoundryChatClient just created, instead of
|
||||
# constructing a second one for the memory provider.
|
||||
memory_provider = FoundryMemoryProvider(
|
||||
project_client=client.project_client,
|
||||
memory_store_name=os.environ["MEMORY_STORE_NAME"],
|
||||
# Scope memories by user id, so each user that interacts with the agent
|
||||
# has their own isolated memories in the store (assuming those users are
|
||||
# granted access). `{{userId}}` is a special placeholder that the hosting
|
||||
# infrastructure will replace with the actual user id at runtime.
|
||||
scope="{{$userId}}",
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
client=client,
|
||||
instructions=(
|
||||
"You are a helpful assistant that remembers facts the user has shared "
|
||||
"across conversations. Relevant memories from previous interactions are "
|
||||
"automatically provided to you in the system context. Use them when "
|
||||
"answering, and acknowledge when you are relying on remembered facts."
|
||||
),
|
||||
context_providers=[memory_provider],
|
||||
# History will be managed by the hosting infrastructure, thus there
|
||||
# is no need to store history by the service. Learn more at:
|
||||
# https://developers.openai.com/api/reference/resources/responses/methods/create
|
||||
default_options={"store": False},
|
||||
)
|
||||
server = ResponsesHostServer(agent)
|
||||
await server.run_async()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
"""Provision the Azure AI Foundry Memory Store used by this sample.
|
||||
|
||||
Creates the memory store named by ``MEMORY_STORE_NAME`` if it does not
|
||||
already exist. The store is configured with the user-profile capability so the
|
||||
agent can remember stable facts about a user across sessions; chat-summary is
|
||||
disabled to keep the demo focused on durable preferences. Safe to re-run: if a
|
||||
store with the same name already exists, the script leaves it alone.
|
||||
|
||||
Usage (from this directory, with the venv activated and ``az login`` done):
|
||||
|
||||
python provision_memory_store.py
|
||||
|
||||
Required env vars (also read from a local ``.env`` file if present):
|
||||
|
||||
FOUNDRY_PROJECT_ENDPOINT e.g. https://<account>.services.ai.azure.com/api/projects/<project>
|
||||
AZURE_AI_MODEL_DEPLOYMENT_NAME Chat model deployment used by the memory store
|
||||
AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME Embedding model deployment used by the memory store
|
||||
MEMORY_STORE_NAME Name of the memory store to create
|
||||
|
||||
Your identity needs ``Azure AI User`` on the Foundry project scope.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.ai.projects.models import (
|
||||
MemoryStoreDefaultDefinition,
|
||||
MemoryStoreDefaultOptions,
|
||||
)
|
||||
from azure.core.exceptions import ResourceNotFoundError
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
|
||||
memory_store_name = os.environ["MEMORY_STORE_NAME"]
|
||||
chat_model = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
|
||||
embedding_model = os.environ["AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME"]
|
||||
|
||||
async with (
|
||||
DefaultAzureCredential() as credential,
|
||||
AIProjectClient(endpoint=endpoint, credential=credential, allow_preview=True) as project,
|
||||
):
|
||||
try:
|
||||
existing = await project.beta.memory_stores.get(name=memory_store_name)
|
||||
print(f"Memory store '{existing.name}' already exists (id={existing.id}); leaving as-is.")
|
||||
return
|
||||
except ResourceNotFoundError:
|
||||
pass
|
||||
|
||||
print(f"Creating memory store '{memory_store_name}'...")
|
||||
definition = MemoryStoreDefaultDefinition(
|
||||
chat_model=chat_model,
|
||||
embedding_model=embedding_model,
|
||||
options=MemoryStoreDefaultOptions(
|
||||
chat_summary_enabled=False,
|
||||
user_profile_enabled=True,
|
||||
user_profile_details=(
|
||||
"Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
|
||||
),
|
||||
),
|
||||
)
|
||||
created = await project.beta.memory_stores.create(
|
||||
name=memory_store_name,
|
||||
description="Memory store for the Agent Framework foundry-hosted memory sample",
|
||||
definition=definition,
|
||||
)
|
||||
print(f"Created memory store '{created.name}' (id={created.id}).")
|
||||
|
||||
# Verify the store actually exists on the service by reading it back.
|
||||
# ``create`` returns the requested definition, but a follow-up ``get``
|
||||
# confirms the store is persisted and reachable for the agent at runtime.
|
||||
try:
|
||||
verified = await project.beta.memory_stores.get(name=memory_store_name)
|
||||
except ResourceNotFoundError as exc:
|
||||
raise RuntimeError(
|
||||
f"Memory store '{memory_store_name}' was not found after creation; "
|
||||
"the service may not have persisted it."
|
||||
) from exc
|
||||
print(f"Verified memory store '{verified.name}' is available on the service (id={verified.id}).")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
agent-framework
|
||||
agent-framework-foundry-hosting
|
||||
azure-ai-projects
|
||||
Reference in New Issue
Block a user