You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
samples(python/13-foundry-memory): one-command azd provisioning via postprovision hook (#576)
Add a postprovision hook (.ps1/.sh) that creates the Foundry Memory Store and wires MEMORY_STORE_NAME so a single 'azd provision' is enough. The hook also patches the init'd agent.yaml so the resolved store name reaches the deployed container (azd ai agent init resolves \ to empty at init time). Pin mcp<2 (agent-framework-foundry-hosting imports McpError, renamed in mcp 2.x). Document the project-scope Cognitive Services OpenAI User role needed for the embedding call. Exclude hooks/ from container/azd packaging.
Copy file name to clipboardExpand all lines: samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/README.md
+72-50Lines changed: 72 additions & 50 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,47 +33,19 @@ The agent is hosted using the [Agent Framework](https://github.com/microsoft/age
33
33
34
34
### Required RBAC
35
35
36
-
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`.
36
+
Your identity (or the Managed Identity running the container in production) needs **Azure AI User** on the Foundry project scope. This role covers provisioning the memory store with `provision_memory_store.py` and reading/writing memories from `main.py`.
37
37
38
-
## Provisioning the memory store (one time)
38
+
The memory store embeds and retrieves memories through the project's inference endpoint, so the same identity also needs **Cognitive Services OpenAI User** on the Foundry project scope to call the embedding deployment. Without it, memory writes fail with a `401` (`Authentication to the Azure OpenAI resource failed`) and the store stays empty. When deploying, grant both roles to the hosted agent's runtime identity (the `…-AgentIdentity` service principal) at the project scope.
39
39
40
-
[`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.
41
-
42
-
From this directory, with the venv activated and `az login` done:
1.**Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later)
48
+
2. Install the unified Foundry CLI extension bundle:
77
49
```bash
78
50
azd ext install microsoft.foundry
79
51
```
@@ -82,7 +54,7 @@ Created memory store 'agent_framework_memory' (id=memstore_...).
82
54
azd auth login
83
55
```
84
56
85
-
### Initialize the agent project
57
+
### 2. Initialize the agent project
86
58
87
59
No cloning required. Create a new folder and initialize from the manifest:
88
60
@@ -92,17 +64,42 @@ mkdir my-memory-agent && cd my-memory-agent
92
64
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/agent.manifest.yaml
93
65
```
94
66
95
-
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.
67
+
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. Initializing also sets the selected project as the active project, and copies this sample's files into a new service directory `src/<agent-name>/` — including [`provision_memory_store.py`](provision_memory_store.py) and the [`hooks/`](hooks/) scripts.
If you don't already have a Foundry project and model deployment:
71
+
Wire the bundled hook into the `azure.yaml` that `azd ai agent init` generated, so the memory store is created automatically every time you run `azd provision`. `postprovision` must be registered at the **top level** of `azure.yaml` (service-scoped hooks only support the package/deploy lifecycle), and the `run:` path must point at the hook inside the generated service directory. Add this top-level block, replacing `<agent-name>` with the service folder `azd ai agent init` created under `src/`:
72
+
73
+
```yaml
74
+
hooks:
75
+
postprovision:
76
+
posix:
77
+
shell: sh
78
+
run: ./src/<agent-name>/hooks/postprovision.sh
79
+
windows:
80
+
shell: pwsh
81
+
run: ./src/<agent-name>/hooks/postprovision.ps1
82
+
```
83
+
84
+
The hook ([`hooks/postprovision.sh`](hooks/postprovision.sh) / [`hooks/postprovision.ps1`](hooks/postprovision.ps1)) runs everything the [manual steps](#provision-manually-without-the-hook) below would, in one shot. It locates its own directory, so it works no matter where `azd` runs it from.
85
+
86
+
### 4. Provision
87
+
88
+
Point the hook at an embedding model deployment in your Foundry project (it powers the store's semantic memory, not the agent at runtime), then provision:
100
89
101
90
```bash
91
+
azd env set AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME "text-embedding-3-small"
102
92
azd provision
103
93
```
104
94
105
-
### Run the agent locally
95
+
`azd provision` creates (or reuses) your Foundry project and chat model deployment, then the `postprovision` hook:
96
+
97
+
1. Runs [`provision_memory_store.py`](provision_memory_store.py) to create the Foundry Memory Store (user-profile capability enabled, chat-summary disabled) and verifies it on the service.
98
+
2. Sets `MEMORY_STORE_NAME` so the agent reads and writes that store. It persists the name both to the `azd` environment (for `azd ai agent run`) and into the generated `src/<agent-name>/agent.yaml` (so `azd deploy` ships it to the container — `azd ai agent init` resolves `${MEMORY_STORE_NAME}` to an empty value at init time, before the store name is known).
99
+
100
+
> The hook defaults `MEMORY_STORE_NAME` to `agent_framework_memory`. To use a different name, set it first: `azd env set MEMORY_STORE_NAME "<your-store-name>"`.
101
+
102
+
### 5. Run the agent locally
106
103
107
104
```bash
108
105
azd ai agent run
@@ -115,35 +112,60 @@ The agent host will start on `http://localhost:8088`.
115
112
In a separate terminal, from the project directory:
116
113
117
114
```bash
118
-
azd ai agent invoke --local "Hi"
115
+
azd ai agent invoke --local "Hi, my name is Alex and I'm vegetarian."
119
116
```
120
117
121
118
### Deploy to Foundry
122
119
123
-
Once tested locally, deploy to Microsoft Foundry:
120
+
```bash
121
+
azd deploy
122
+
```
123
+
124
+
For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
125
+
126
+
The deployed agent's Managed Identity needs **Azure AI User** on the Foundry project to read and write memories at runtime. The `postprovision` hook already created the memory store against that same project.
124
127
125
-
Make sure `MEMORY_STORE_NAME` is set in your `azd` environment:
128
+
### Invoke the deployed agent
126
129
127
130
```bash
128
-
azd env set MEMORY_STORE_NAME "agent_framework_memory"
131
+
azd ai agent invoke "Do you remember my name and what I like to eat?"
129
132
```
130
133
134
+
### Provision manually (without the hook)
135
+
136
+
Prefer to run the step yourself (or skip the hook)? [`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.
137
+
138
+
From the project directory, with the venv activated and `az login` done:
For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
150
+
In PowerShell, use `$env:NAME="value"` instead of `export`. Then point the agent at the same store name:
136
151
137
-
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.
152
+
```bash
153
+
azd env set MEMORY_STORE_NAME "agent_framework_memory"
154
+
```
138
155
139
-
### Invoke the deployed agent
156
+
Expected output (first run):
140
157
141
-
```bash
142
-
azd ai agent invoke "Hi"
158
+
```text
159
+
Creating memory store 'agent_framework_memory'...
160
+
Created memory store 'agent_framework_memory' (id=memstore_...).
143
161
```
144
162
163
+
> To delete the store manually, call `project.beta.memory_stores.delete("<name>")` on an `AIProjectClient` constructed with `allow_preview=True`.
164
+
145
165
## Option 2: VS Code (Foundry Toolkit)
146
166
167
+
> The VS Code flow doesn't run the `azd` hook — provision the memory store first with [Provision manually](#provision-manually-without-the-hook).
168
+
147
169
### Prerequisites
148
170
149
171
1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed.
![foundry-samples-repo-sync[bot]](https://avatars.githubusercontent.com/u/42854725?v=4&size=40){kind=avatar}
0 commit comments