Quickstart: Give a hosted agent persistent memory

Provision a Foundry memory store, then deploy a Python hosted agent that remembers facts about each user across sessions by using FoundryMemoryProvider.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

In this quickstart, you give a hosted agent persistent, semantic memory backed by a Foundry memory store. Without memory, every conversation starts from scratch. With a memory store, the agent retains stable facts about a user, such as a name or a dietary preference, and recalls them in later sessions.

You complete two parts:

• Provision a memory store and wire it to the agent. In the Azure Developer CLI path, a bundled provisioning hook runs after azd provision. In the Python path, you create the store directly with the SDK. The store uses a chat model and an embedding model to extract and index user-profile memories.
• Deploy a hosted agent that reads and writes the store through FoundryMemoryProvider. The provider retrieves relevant memories before each model call and updates the store with new facts after each turn.

The agent code, memory provider, and authentication come from the Foundry memory sample, so you focus on the workflow rather than the implementation.

Prerequisites

This quickstart builds on the hosted-agent toolchain. Complete the Prerequisites in the hosted agent quickstart first, which cover the Azure subscription, project roles, Python, the Azure Developer CLI (azd), and the microsoft.foundry extension.

You also need an embedding model deployment in your Foundry project, such as text-embedding-3-small. The memory store uses it to index memories. The agent’s chat model, such as gpt-4o, can be the deployment you already use for hosted agents.

Your identity needs the Foundry User role on the Foundry project scope through the hosted-agent prerequisites, and it also needs the Cognitive Services OpenAI User role on the same scope. The memory store uses Foundry project data-plane access plus the embedding deployment. Without the OpenAI role, memory writes fail with a 401 error and the store stays empty.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Clean up resources

Delete the resources when you’re finished so you stop incurring charges.

Troubleshooting

Issue	Solution
The deployed agent has no memory, or MEMORY_STORE_NAME is empty	Confirm the postprovision hook ran during azd provision and that azure.yaml has MEMORY_STORE_NAME set. Rerun azd provision to run the hook again.
Memory writes fail with a 401 error and the store stays empty	Confirm the caller already has Foundry User access on the Foundry project scope, and grant the Cognitive Services OpenAI User role on the same scope to your identity and to the deployed agent’s runtime identity.
azd provision fails with a permissions error	Confirm your identity has the project roles listed in the Prerequisites.
project.beta.memory_stores.create(...) fails with Authentication to the Azure OpenAI resource failed	Confirm your identity already has Foundry User access on the Foundry project scope, and also has the Cognitive Services OpenAI User role on that scope. Also verify that AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME points to a valid embedding deployment.
The Python deployment succeeds but the second call doesn’t recall the stored fact	Wait a few more seconds before the second call so the memory store finishes indexing, then run the script again.
The agent doesn’t recall a fact you shared	Allow a few seconds after storing a fact before you query, so the store finishes indexing the memory.
The agent can’t read or write memories after deployment	Confirm that the postprovision hook created the store against the same project the agent is deployed to.

What you learned

In this quickstart, you:

• Created a Foundry memory store with the user-profile capability.
• Deployed a hosted agent that reads and writes to the store through FoundryMemoryProvider by using Azure Developer CLI or the Python SDK.
• Verified that the agent recalls user facts across separate sessions, either locally with Azure Developer CLI or remotely with the Python SDK after deployment.

Next step

Evaluate your hosted agent

Related content

• What are hosted agents?
• Attach memory to an agent
• Quickstart: Deploy your first hosted agent
• Manage hosted agents