Important
이 문서에서 미리 보기로 표시된 항목은 현재 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 Microsoft 프로덕션 워크로드에 권장하지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
이 빠른 시작에서는 Foundry 메모리 저장소를 기반으로 하는 영구적인 시맨틱 메모리를 호스트된 에이전트에 부여합니다. 메모리가 없으면 모든 대화가 처음부터 시작됩니다. 메모리 저장소를 사용하면 에이전트는 이름 또는 식이 선호도와 같은 사용자에 대한 안정적인 사실을 유지하고 이후 세션에서 이를 회수합니다.
다음 두 부분을 완료합니다.
-
메모리 저장소를 프로비전 하고 에이전트에 연결합니다. Azure Developer CLI 경로에서는
azd provision후에 기본 제공되는 프로비저닝 후크가 실행됩니다. Python 경로에서 SDK를 사용하여 직접 저장소를 만듭니다. 스토어는 채팅 모델 및 포함 모델을 사용하여 사용자 프로필 추억을 추출하고 인덱싱합니다. - . 공급자는 각 모델 호출 전에 관련 추억을 검색하고 각 턴 후에 새 팩트를 사용하여 저장소를 업데이트합니다.
에이전트 코드, 메모리 공급자 및 인증은 Foundry 메모리 샘플에서 제공되므로 구현보다는 워크플로에 집중합니다.
GitHub Copilot 같은 코딩 에이전트를 사용하는 경우 Microsoft Foundry Skill은 메모리 저장소를 프로비전하고 호스트된 에이전트에 연결하고 회수 동작을 테스트하는 데 도움이 될 수 있습니다.
사전 요구 사항
이 빠른 시작은 호스트 에이전트 도구 체인을 기반으로 합니다. 먼저 호스트된 에이전트 빠른 시작에서 필수 구성 요소를 완료합니다. 이 빠른 시작에서는 Azure 구독, 프로젝트 역할, Python, Azure 개발자 CLI(azd) 및 microsoft.foundry 확장을 다룹니다.
이 경로의 Azure Developer CLI를 사용하여 샘플을 스캐폴드하고, 번들된 postprovision 후크를 통해 메모리 저장소를 프로비전하고, 에이전트를 로컬로 실행하고, 배포합니다.
이 경로에서 Python SDK를 사용하여 메모리 저장소AIProjectClient.beta.memory_stores.create(...)를 만들고, 호스트 에이전트 코드를 새 버전으로 업로드하고, 트래픽을 일시적으로 라우팅하고, 동일한 로그인한 사용자가 별도의 호출에서 기억되고 있는지 확인합니다.
이 경로에 사용되는 Python 패키지를 설치합니다.
pip install "azure-ai-projects>=2.3.0" python-dotenv
이 경로에서 .NET SDK를 사용하여 메모리 저장소AIProjectClient.MemoryStores.CreateMemoryStore(...)를 만들고, 호스트 에이전트 코드를 새 버전으로 업로드하고, 트래픽을 일시적으로 라우팅하고, 동일한 로그인한 사용자가 별도의 호출에서 기억되고 있는지 확인합니다.
.NET 10 SDK 이상도 필요합니다.
또한 Foundry 프로젝트에서 임베딩 모델 배포가 필요합니다(예: text-embedding-3-small). 메모리 저장소는 이를 사용하여 메모리를 인덱싱합니다. 에이전트의 채팅 모델(예: gpt-4o)은 호스팅된 에이전트에 현재 사용 중인 배포일 수 있습니다.
사용자 ID에는 호스팅된 에이전트 필수 구성 요소에 따라 Foundry 프로젝트 범위에 대한 Foundry User 역할이 필요하며, 동일한 범위에 대한 Cognitive Services OpenAI User 역할도 필요합니다. 메모리 저장소는 Foundry 프로젝트 데이터 플레인 액세스와 임베딩 배포를 사용합니다. OpenAI 역할이 없으면 메모리 쓰기가 401 오류로 실패하고 저장소가 비어 있습니다.
Important
Foundry RBAC 역할의 이름이 최근에 바뀌었습니다. Foundry User, Foundry OwnerFoundry 계정 소유자 및 Foundry Project Manager는 이전에 Azure AI 사용자, Azure AI 소유자, Azure AI 계정 소유자 및 Azure AI Project Manager로 이름이 지정되었습니다. 이름 바꾸기가 롤아웃되는 동안 일부 위치에서는 이전 이름이 계속 표시될 수 있습니다. 역할 ID 및 핵심 권한은 이름 바꾸기에 의해 변경되지 않습니다.
1단계: 호스트된 에이전트 초기화
Foundry 메모리 샘플에서 호스팅된 에이전트를 초기화합니다. 초기화는 메모리 저장소 프로비저닝 스크립트 및 프로비전 후크를 포함한 샘플 파일을 아래 src/의 새 서비스 디렉터리에 복사합니다. 빈 디렉터리에서 이러한 명령을 실행합니다.
mkdir my-memory-agent
cd my-memory-agent
azd ai agent init -t "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/azure.yaml"
프롬프트에 따라 구독, 프로젝트 및 모델 배포를 선택합니다. Foundry 프로젝트가 없는 경우 azd ai agent init가 프로젝트를 만드는 과정을 안내합니다.
Python 에이전트를 실행하거나 배포하기 전에 env의 해당 서비스가 기존 PYTHONNOUSERSITE: "1" 맵에 azure.yaml을(를) 포함하고 있는지 확인합니다. 종속성 호환성에 대해서는 Python 시작 구성을 참조하세요.
2단계: 한 번의 명령으로 프로비저닝 활성화
샘플에는 메모리 저장소를 생성하고 postprovision를 실행할 때마다 이를 에이전트에 자동으로 연결하는 azd provision 후크가 포함되어 있습니다. 생성된 파일 azure.yaml 의 azd ai agent init 최상위 수준에 후크를 등록합니다.
azure.yaml 다음 최상위 블록을 열고 추가합니다.
<agent-name>를 src/ 아래에 초기화가 생성한 서비스 폴더로 바꾸세요:
hooks:
postprovision:
posix:
shell: sh
run: ./src/<agent-name>/hooks/postprovision.sh
windows:
shell: pwsh
run: ./src/<agent-name>/hooks/postprovision.ps1
후크는 스스로 위치를 찾으며 멱등성을 가집니다. 어느 디렉터리에서 azd 호출하더라도 올바르게 실행되며, 다시 실행해도 기존 저장소는 그대로 유지됩니다.
메모
postprovision의 최상위 수준에 azure.yaml을 등록합니다. 서비스 범위의 후크는 패키지 및 배포 수명 주기만 지원하며, 프로비저닝은 지원하지 않습니다.
3단계: 메모리 저장소 및 Azure 리소스 프로비전
저장소의 시맨틱 메모리를 구동하는 임베딩 모델 배포를 가리키도록 후크를 설정합니다.
azd env set AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME "text-embedding-3-small"제공:
azd provision
azd provision는 Foundry 프로젝트 및 채팅 모델 배포를 만들거나 재사용합니다. 다음으로 postprovision 훅:
- 사용자 프로필 기능을 사용하도록 설정된 메모리 저장소를 만들고 서비스에서 확인합니다.
- 에이전트가 해당 저장소를 읽고 쓰도록 설정합니다
MEMORY_STORE_NAME. 후크는 로컬 실행을 위해 이름을 사용자의azd환경에 저장하고,azure.yaml의 서비스 환경에도 저장하므로azd deploy가 이를 컨테이너로 전달합니다.
CLI 경로에서는 번들된 후크가 create memory store의 일부로 해당 생성 로직을 대신 실행하므로 별도의 azd provision 명령이 표시되지 않습니다.
후크는 기본적으로 저장소 이름을 .로 설정합니다 agent_framework_memory. 다른 이름을 사용하려면 프로비전하기 전에 설정합니다.
azd env set MEMORY_STORE_NAME "<your-store-name>"
4단계: 에이전트를 로컬로 실행
에이전트를 시작합니다.
azd ai agent run이 명령은 가상 환경을 만들고, 종속성을 설치하고, 에이전트를 제공합니다
http://localhost:8088. 후크가 이미 사용 중인MEMORY_STORE_NAME환경에서azd를 설정하므로 별도의 추가 구성이 필요하지 않습니다. 미리 보기 패키지는 설치 중에 pip 경고를 생성할 수 있습니다. 이러한 경고는 차단되지 않습니다.별도의 터미널에서 에이전트에 자신에 대한 사실을 알려주세요.
azd ai agent invoke --local "Hi! My name is Linda and I'm vegetarian. Please remember that."새 세션을 시작하고 에이전트가 대화 기록이 아니라 저장소에서 해당 사실을 불러오는지 확인합니다.
azd ai agent invoke --local --new-session "Do you remember my name and any dietary preference I told you earlier?"에이전트는 사용자 이름과 기본 설정으로 대답하며, 이는 메모리 저장소에서 검색되었음을 증명합니다.
5단계: Foundry 에이전트 서비스에 배포
에이전트 소스 코드를 배포합니다.
azd 는 원본을 ZIP 파일로 패키지하고 Foundry에 업로드하여 종속성을 확인하고 호스트된 에이전트를 원격으로 빌드합니다.
postprovision 후크는 이미 MEMORY_STORE_NAME를 azure.yaml에 기록하므로 배포된 에이전트는 동일한 저장소를 읽습니다:
azd deploy
명령이 완료되면 출력에 에이전트 플레이그라운드 및 에이전트 엔드포인트에 대한 링크가 표시됩니다. 배포된 에이전트의 세션 간에 메모리를 확인합니다. 팩트 저장:
azd ai agent invoke --new-session "Hi! My name is Marco and I'm allergic to peanuts. Please remember this about me."
그런 다음, 새 세션에서 다시 기억하세요.
azd ai agent invoke --new-session "What's my name, and is there any food I should avoid?"
배포된 에이전트는 기억된 이름과 알레르기로 답변합니다.
1단계: Foundry 프로젝트 만들기 또는 선택
Foundry 포털을 열고 Foundry 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
프로젝트에서 다음을 배포합니다.
- 채팅 가능 모델(예:
gpt-5.4-mini. - 임베딩 모델(예:
text-embedding-3-small).
- 채팅 가능 모델(예:
개요에서 프로젝트 엔드포인트를, 빌드>배포에서 배포 이름을 복사합니다.
2단계: Foundry 메모리 샘플 다운로드
Foundry 샘플 리포지토리를 복제합니다.
git clone https://github.com/microsoft-foundry/foundry-samples.git
배포 스크립트에 대한 작업 폴더를 만듭니다. 해당 폴더에서 다음 값을 가진 .env 파일을 만듭니다.
FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-chat-model-deployment-name>
AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME=<your-embedding-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=memory-agent
MEMORY_STORE_NAME=agent_framework_memory
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/src/agent-framework-agent-foundry-memory-responses>
3단계: Python 사용하여 메모리 저장소 프로비전
이 스크립트는 다시 실행해도 안전합니다. 먼저 메모리 저장소가 이미 있는지 확인하기 위해 호출 get(...) 합니다. 스토어를 찾을 수 없는 경우에만 create(...)만 호출됩니다.
다음과 같은 작업 폴더provision_memory_store.py에 이름이 지정된 .env 파일을 만듭니다.
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 "
f"(id={existing.id}); leaving as-is."
)
return
except ResourceNotFoundError:
pass
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 hosted-agent memory quickstart",
definition=definition,
)
print(f"Created memory store '{created.name}' (id={created.id}).")
asyncio.run(main())
스크립트를 실행합니다.
python provision_memory_store.py
4단계: Python 사용하여 호스트된 에이전트 배포
다음과 같은 작업 폴더deploy_memory_agent.py에 이름이 지정된 .env 파일을 만듭니다.
import os
import tempfile
import time
import zipfile
from pathlib import Path
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
AgentEndpointConfig,
CodeConfiguration,
CodeDependencyResolution,
FixedRatioVersionSelectionRule,
HostedAgentDefinition,
ProtocolConfiguration,
ProtocolVersionRecord,
ResponsesProtocolConfiguration,
VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "memory-agent")
memory_store_name = os.environ["MEMORY_STORE_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()
def create_code_zip(source_dir: Path) -> Path:
zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
excluded = {".git", ".venv", "__pycache__", ".env"}
with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
for path in source_dir.rglob("*"):
if not path.is_file():
continue
if any(part in excluded for part in path.parts):
continue
zip_file.write(path, path.relative_to(source_dir))
return zip_path
def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
for attempt in range(60):
time.sleep(10)
details = project_client.agents.get_version(
agent_name=agent_name,
agent_version=version,
)
status = details["status"]
print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")
if status == "active":
return
if status == "failed":
raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")
raise RuntimeError("Timed out waiting for the hosted agent version to become active.")
code_zip_path = create_code_zip(sample_path)
with (
code_zip_path.open("rb") as code_stream,
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=endpoint,
credential=credential,
allow_preview=True,
) as project_client,
):
original_agent_endpoint = None
created = None
try:
created = project_client.agents.create_version_from_code(
agent_name=agent_name,
description="Hosted agent with persistent Foundry memory.",
definition=HostedAgentDefinition(
cpu="0.5",
memory="1Gi",
code_configuration=CodeConfiguration(
runtime="python_3_13",
entry_point=["python", "main.py"],
dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
),
environment_variables={
"FOUNDRY_PROJECT_ENDPOINT": endpoint,
"AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
"MEMORY_STORE_NAME": memory_store_name,
"PYTHONNOUSERSITE": "1",
},
protocol_versions=[
ProtocolVersionRecord(protocol="responses", version="2.0.0")
],
),
code=code_stream,
)
print(f"Created hosted agent version {created.version}")
wait_for_active_version(project_client, created.version)
original_agent_endpoint = project_client.agents.get(
agent_name=agent_name
).agent_endpoint
project_client.agents.update_details(
agent_name=agent_name,
agent_endpoint=AgentEndpointConfig(
version_selector=VersionSelector(
version_selection_rules=[
FixedRatioVersionSelectionRule(
agent_version=created.version,
traffic_percentage=100,
),
]
),
protocol_configuration=ProtocolConfiguration(
responses=ResponsesProtocolConfiguration()
),
),
)
with project_client.get_openai_client(agent_name=agent_name) as openai_client:
first_response = openai_client.responses.create(
input="Hi! My name is Linda and I'm vegetarian. Please remember that.",
)
print(first_response.output_text)
time.sleep(10)
second_response = openai_client.responses.create(
input=(
"Do you remember my name and any dietary preference I told "
"you earlier?"
),
)
print(second_response.output_text)
finally:
if original_agent_endpoint is not None:
project_client.agents.update_details(
agent_name=agent_name,
agent_endpoint=original_agent_endpoint,
)
if created is not None:
project_client.agents.delete_version(
agent_name=agent_name,
agent_version=created.version,
force=True,
)
스크립트를 실행합니다.
python deploy_memory_agent.py
이 스크립트는 메모리 샘플을 새 호스티드 에이전트 버전으로 업로드하고, 해당 버전에서 호스트된 에이전트를 일시적으로 가리키고, 동일한 로그인 사용자로 두 번 호출하고, 완료되면 이전 엔드포인트 구성을 복원합니다.
5단계: 메모리가 유지되는지 확인
첫 번째 호출은 팩트가 메모리 저장소에 저장됩니다. 두 번째 호출은 별도의 요청을 통해 기억해 둔 사실을 요청합니다. 메모리 저장소가 올바르게 구성된 경우 응답은 첫 번째 요청에서 제공한 것과 동일한 이름과 식이 기본 설정을 언급해야 합니다.
1단계: Foundry 프로젝트 만들기 또는 선택
Foundry 포털을 열고 Foundry 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
프로젝트에서 다음을 배포합니다.
- 채팅 가능 모델(예:
gpt-4o. - 임베딩 모델(예:
text-embedding-3-small).
- 채팅 가능 모델(예:
개요에서 프로젝트 엔드포인트를, 빌드>배포에서 배포 이름을 복사합니다.
2단계: Foundry 메모리 샘플 다운로드
Foundry 샘플 리포지토리를 복제합니다.
git clone https://github.com/microsoft-foundry/foundry-samples.git
C# 호스트 에이전트 샘플은 아래에 있습니다 samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag.
다음 단계에서는 해당 폴더를 호스트된 에이전트 버전으로 배포합니다. 샘플은 배포 코드가 컨테이너에 설정하는 이러한 환경 변수에서 해당 구성을 읽습니다.
| Variable | 설명 |
|---|---|
FOUNDRY_PROJECT_ENDPOINT |
Foundry 프로젝트 엔드포인트입니다. |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
채팅 모델 배포 이름입니다. |
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME |
모델 배포 이름 포함 |
AZURE_AI_MEMORY_STORE_ID |
메모리 저장소 이름입니다. 기본값은 foundry-memory-rag-store입니다. |
3단계: C를 사용하여 메모리 저장소 프로비전#
.NET 콘솔 앱을 만들고 패키지를 설치합니다. 메모리 저장소 API는 미리 보기 상태이므로 시험판 Azure.AI.Projects 패키지를 설치합니다.
dotnet new console --name provision-memory-store
cd provision-memory-store
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
이 코드는 다시 실행해도 안전합니다. 먼저 저장소 GetMemoryStore(...) 가 이미 있는지 확인하고 저장소를 찾을 수 없는 경우에만 호출 CreateMemoryStore(...) 합니다.
Program.cs를 다음 코드로 교체한 다음 embeddingModel, endpoint, chatModel을 프로젝트 값으로 설정하세요:
using System.ClientModel;
using Azure.AI.Projects;
using Azure.AI.Projects.Memory;
using Azure.Identity;
#pragma warning disable AAIP001
var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var memoryStoreName = "foundry-memory-rag-store";
AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
try
{
MemoryStore existing = projectClient.MemoryStores.GetMemoryStore(memoryStoreName);
Console.WriteLine($"Memory store '{existing.Name}' already exists (id={existing.Id}); leaving as-is.");
}
catch (ClientResultException ex) when (ex.Status == 404)
{
MemoryStore created = projectClient.MemoryStores.CreateMemoryStore(
memoryStoreName,
new MemoryStoreDefaultDefinition(chatModel, embeddingModel)
{
Options = new MemoryStoreDefaultOptions(isUserProfileEnabled: true, isChatSummaryEnabled: false)
{
UserProfileDetails =
"Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials",
},
},
description: "Memory store for the hosted-agent memory quickstart");
Console.WriteLine($"Created memory store '{created.Name}' (id={created.Id}).");
}
앱을 실행합니다.
dotnet run
4단계: C를 사용하여 호스트된 에이전트 배포#
배포 코드에 대한 두 번째 콘솔 앱을 만듭니다.
dotnet new console --name deploy-memory-agent
cd deploy-memory-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
에서 Program.cs기존 코드를 다음 코드로 바꿉다.
chatModel, embeddingModel, samplePath 및 endpoint를 원하는 값으로 설정합니다.
samplePath 는 2단계에서 복제한 원본 폴더의 foundry-memory-rag 전체 경로입니다.
using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;
#pragma warning disable AAIP001, OPENAI001
var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var agentName = "memory-agent";
var memoryStoreName = "foundry-memory-rag-store";
var samplePath =
@"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-memory-rag\src\foundry-memory-rag";
AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;
HostedAgentDefinition definition = new(cpu: "0.5", memory: "1Gi")
{
Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
CodeConfiguration = new(
runtime: "dotnet_10",
entryPoint: ["dotnet", "foundry-memory-rag.dll"],
dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME", embeddingModel);
definition.EnvironmentVariables.Add("AZURE_AI_MEMORY_STORE_ID", memoryStoreName);
ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
created = agentsClient.CreateAgentVersionFromCode(
agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
Console.WriteLine($"Created hosted agent version {created.Version}");
for (var attempt = 1; attempt <= 60; attempt++)
{
Thread.Sleep(TimeSpan.FromSeconds(10));
created = agentsClient.GetAgentVersion(agentName, created.Version);
Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
if (created.Status == AgentVersionStatus.Active) break;
if (created.Status == AgentVersionStatus.Failed)
throw new InvalidOperationException("Hosted agent provisioning failed.");
}
ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
originalEndpoint = agent.AgentEndpoint;
agentsClient.PatchAgent(agentName, new PatchAgentOptions
{
AgentEndpoint = new AgentEndpointConfiguration
{
VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
},
});
ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
.GetProjectResponsesClientForAgentEndpoint(agentName);
ResponseResult first = responsesClient.CreateResponse(
"Hi! My name is Linda and I'm vegetarian. Please remember that.");
Console.WriteLine(first.GetOutputText());
Thread.Sleep(TimeSpan.FromSeconds(10));
ResponseResult second = responsesClient.CreateResponse(
"Do you remember my name and any dietary preference I told you earlier?");
Console.WriteLine(second.GetOutputText());
}
finally
{
if (originalEndpoint is not null)
agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
if (created is not null)
agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}
앱을 실행합니다.
dotnet run
이 코드는 메모리 샘플을 새 호스트 에이전트 버전으로 업로드하고, 해당 버전에서 호스트된 에이전트를 일시적으로 가리키고, 동일한 로그인 사용자로 두 번 호출하고, 완료 시 이전 엔드포인트 구성을 복원합니다.
5단계: 메모리가 유지되는지 확인
첫 번째 호출은 팩트가 메모리 저장소에 저장됩니다. 두 번째 호출은 별도의 요청을 통해 기억해 둔 사실을 요청합니다. 메모리 저장소가 올바르게 구성된 경우 응답은 첫 번째 요청에서 제공한 것과 동일한 이름과 식이 기본 설정을 언급합니다. 메모리 추출은 비동기이므로 저장소가 메모리를 인덱싱하는 두 호출 사이에 몇 초 정도 허용합니다.
자원을 정리하세요
완료되면 리소스를 삭제하여 요금 발생을 중지합니다.
메모리 저장소를 삭제하려면 .를 사용합니다 AIProjectClient.
azure-ai-projects 및 azure-identity 패키지가 설치된 Python 환경에서 이 스크립트를 실행하세요(예: pip install "azure-ai-projects>=2.3.0" 실행).
import asyncio
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
async def delete():
async with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint="https://<account>.services.ai.azure.com/api/projects/<project>",
credential=credential,
allow_preview=True,
) as project,
):
await project.beta.memory_stores.delete("agent_framework_memory")
asyncio.run(delete())
에이전트 및 해당 Azure 리소스를 삭제합니다.
Warning
현재 azd 환경에서 Foundry 프로젝트를 만든 경우 프로젝트의 azd down 리소스 그룹 및 해당 프로젝트의 모든 항목을 영구적으로 삭제합니다. 초기화 중에 기존 프로젝트를 선택한 경우 프로젝트, azd down 해당 리소스 그룹, 호스트된 에이전트 및 기타 빠른 시작 리소스를 제자리에 둡니다. 기존 프로젝트에서 더 이상 필요하지 않은 리소스를 삭제하려면 별도로 삭제합니다.
azd down
메모리 저장소를 삭제하려면 메모리 저장소 이름과 동일한 스크립트 패턴을 사용합니다.
import asyncio
import os
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
async def delete() -> None:
async with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project,
):
await project.beta.memory_stores.delete(os.environ["MEMORY_STORE_NAME"])
asyncio.run(delete())
이 빠른 시작을 위해 전용 리소스 그룹 또는 프로젝트를 만든 경우, 채팅 배포, 임베딩 배포 또는 호스팅된 에이전트가 더 이상 필요 없게 되면 Azure 포털에서 해당 리소스 그룹 또는 프로젝트를 삭제하세요.
배포 코드는 호스트된 에이전트 버전을 이미 삭제하고 완료되면 이전 엔드포인트 구성을 복원합니다. 메모리 저장소를 삭제하려면 Azure.Identity(사전 출시 버전) 및 Azure.AI.Projects 패키지가 설치된 콘솔 앱에 다음 코드를 추가하세요.
using Azure.AI.Projects;
using Azure.Identity;
#pragma warning disable AAIP001
var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var memoryStoreName = "foundry-memory-rag-store";
AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.MemoryStores.DeleteMemoryStore(memoryStoreName);
Console.WriteLine($"Deleted memory store '{memoryStoreName}'.");
이 빠른 시작을 위해 전용 리소스 그룹 또는 프로젝트를 만든 경우, 채팅 배포, 임베딩 배포 또는 호스팅된 에이전트가 더 이상 필요 없게 되면 Azure 포털에서 해당 리소스 그룹 또는 프로젝트를 삭제하세요.
Troubleshooting
| Issue | 해결 방법 |
|---|---|
배포된 에이전트에 메모리 MEMORY_STORE_NAME 가 없거나 비어 있습니다. |
postprovision 동안 azd provision 후크가 실행되었는지, 그리고 azure.yaml에 MEMORY_STORE_NAME가 설정되어 있는지 확인하세요. 다시 실행 azd provision 하여 후크를 다시 실행합니다. |
오류로 메모리 쓰기가 401 실패하고 저장소가 비어 있습니다. |
호출자에게 Foundry 프로젝트 범위에 대한 Foundry 사용자 액세스 권한이 이미 있는지 확인하고 동일한 범위의 Cognitive Services OpenAI 사용자 역할을 ID 및 배포된 에이전트의 런타임 ID에 부여합니다. |
azd provision 사용 권한 오류와 함께 실패 |
사용자 ID에 사전 요구 사항에 나열된 프로젝트 역할이 할당되어 있는지 확인하세요. |
project.beta.memory_stores.create(...)이(가) Authentication to the Azure OpenAI resource failed와 함께 실패함 |
사용자 ID에 Foundry 프로젝트 범위에 대한 Foundry 사용자 액세스 권한이 이미 있고, 해당 범위에 대한 Cognitive Services OpenAI 사용자 역할도 있는지 확인하세요. 또한 AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME이(가) 유효한 임베딩 배포를 가리키는지 확인하세요. |
| Python 배포는 성공하지만 두 번째 호출은 저장된 사실을 기억하지 않습니다. | 메모리 저장소가 인덱싱을 완료하도록 두 번째 호출 전에 몇 초 더 기다린 다음 스크립트를 다시 실행합니다. |
| 에이전트는 공유한 사실을 기억하지 않습니다. | 쿼리하기 전에 팩트를 저장한 후 몇 초 정도 허용하면 저장소가 메모리 인덱싱을 완료합니다. |
| 배포 후 에이전트가 추억을 읽거나 쓸 수 없습니다. |
postprovision 후크가 에이전트가 배포된 동일한 프로젝트에 대해 저장소를 생성했는지 확인합니다. |
배운 내용
이 빠른 시작에서 당신은 다음을 수행합니다.
- 사용자 프로필 기능을 사용하여 Foundry 메모리 저장소를 만들었습니다.
- Azure Developer CLI, Python SDK 또는 .NET SDK를 사용하여 저장소
FoundryMemoryProvider를 읽고 쓰는 호스트된 에이전트를 배포했습니다. - 에이전트가 Azure Developer CLI로 로컬에서, 또는 배포 후 Python 또는 .NET SDK로 원격에서 서로 다른 세션에 걸쳐 사용자 관련 정보를 기억하는지 확인했습니다.