다음을 통해 공유

Foundry 에이전트 서비스에서 메모리 만들기 및 사용(미리 보기)

중요합니다

Foundry 에이전트 서비스의 메모리(미리 보기) 및 메모리 저장소 API(미리 보기)는 Azure 구독의 일부로서 사용자에게 라이선스가 부여되며, 이는 Microsoft 제품 약관, Microsoft 제품 및 서비스 데이터 보호 부록의 "미리 보기" 조건, 그리고 Microsoft Azure 미리 보기 추가 사용 약관에 명시된 Microsoft 생성 AI Services 미리 보기 조건이 적용됩니다.

Foundry 에이전트 서비스의 메모리는 관리되는 장기 메모리 솔루션입니다. 이를 통해 세션, 디바이스 및 워크플로에서 에이전트 연속성을 사용할 수 있습니다. 메모리 저장소를 만들고 관리하면 사용자 기본 설정을 유지하고 대화 기록을 유지하며 개인 설정된 환경을 제공하는 에이전트를 빌드할 수 있습니다.

메모리 저장소는 영구적 스토리지 역할을 하며 각 에이전트와 관련된 정보 유형을 정의합니다. 보안 및 격리된 환경을 보장하기 위해 사용자 간에 메모리를 분할하는 매개 변수를 사용하여 scope 액세스를 제어합니다.

이 문서에서는 메모리 저장소를 만들고 관리하고 사용하는 방법을 설명합니다. 개념 정보는 Foundry 에이전트 서비스의 메모리를 참조하세요.

사용량 지원

역량 Python SDK REST API
메모리 저장소 만들기, 업데이트, 나열 및 삭제 ✔️ ✔️
메모리 업데이트 및 검색 ✔️ ✔️
프롬프트 에이전트에 메모리 연결 ✔️ ✔️

필수 조건

권한 부여 및 퍼미션

프로덕션 배포에 대한 역할 기반 액세스 제어 를 권장합니다. 역할이 적합하지 않은 경우 이 섹션을 건너뛰고 대신 키 기반 인증을 사용합니다.

역할 기반 액세스를 구성하려면 다음을 수행합니다.

  1. Azure Portal에 로그인합니다.
  2. 프로젝트에서:
    1. 왼쪽 창에서 리소스 관리>ID를 선택합니다.
    2. 토글을 사용하여 시스템 할당 관리 ID를 사용하도록 설정합니다.
  3. 프로젝트가 포함된 리소스에서 다음을 수행합니다.
    1. 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.
    2. 추가>역할 할당 추가를 선택합니다.
    3. 프로젝트의 관리 ID에 Azure AI 사용자를 할당합니다.

프로젝트 엔드포인트 설정

이 문서의 Python 예제의 경우 프로젝트 엔드포인트에 대한 환경 변수를 설정합니다.

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

$env:FOUNDRY_PROJECT_ENDPOINT = "https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

범위 이해

매개 변수는 scope 메모리 분할 방법을 제어합니다. 메모리 저장소의 각 범위는 메모리 항목의 격리된 컬렉션을 유지합니다. 예를 들어 메모리가 있는 고객 지원 에이전트를 만드는 경우 각 고객에게는 고유한 개별 메모리가 있어야 합니다.

개발자는 메모리 항목을 저장하고 검색하는 데 사용되는 키를 선택합니다. 시스템에서 UUID(범용 고유 식별자) 또는 다른 안정적인 식별자와 같은 정적 값을 전달할 수 있습니다.

또는 범위로 지정 {{$userId}} 하면 시스템에서 요청 인증 헤더에서 TID(테넌트 ID) 및 OID(개체 ID)를 자동으로 추출합니다. 이 방법은 인증된 각 사용자에게 고유한 격리된 메모리 파티션을 제공하여 식별자를 수동으로 관리할 필요가 없습니다.

메모리 저장소 만들기

각 에이전트에 대한 전용 메모리 저장소를 만들어 메모리 액세스 및 최적화에 대한 명확한 경계를 설정합니다. 메모리 저장소를 만들 때는 채팅 모델을 지정하고 메모리 콘텐츠를 처리하는 모델 배포를 포함합니다.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

memory_store_name = "my_memory_store"

# Specify memory store options
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
    user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
)

# Create memory store
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",  # Your chat model deployment name
    embedding_model="text-embedding-3-small",  # Your embedding model deployment name
    options=options
)

memory_store = project_client.beta.memory_stores.create(
    name=memory_store_name,
    definition=definition,
    description="Memory store for customer support agent",
)

print(f"Created memory store: {memory_store.name}")

메모리 사용자 지정

에이전트가 저장하는 정보를 사용자 지정하여 메모리 효율적이고 관련성이 높으며 개인 정보 보호를 유지합니다. 매개 변수를 user_profile_details 사용하여 에이전트의 함수에 중요한 데이터 형식을 지정합니다.

예를 들어 여행사에 대해 "항공사 선호도 및 식이 제한"의 우선 순위를 지정하도록 설정합니다 user_profile_details . 이 집중 접근 방식은 메모리 시스템에서 장기 메모리를 추출, 요약 및 커밋할 세부 정보를 파악하는 데 도움이 됩니다.

또한 이 매개 변수를 사용하여 특정 형식의 데이터를 제외하여 메모리를 상체로 유지하고 개인 정보 요구 사항을 준수할 수 있습니다. 예를 들어 "나이, 재무, 정확한 위치 및 자격 증명과 같은 관련이 없거나 중요한 데이터를 방지"로 설정합니다 user_profile_details .

메모리 저장소 업데이트

메모리 저장소를 보다 효율적으로 관리하도록 메모리 저장소 속성(예: description 또는 metadata)을 업데이트합니다.

# Update memory store properties
updated_store = project_client.beta.memory_stores.update(
    name=memory_store_name,
    description="Updated description"
)

print(f"Updated: {updated_store.description}")

메모리 저장소 나열

프로젝트의 메모리 저장소 목록을 검색하여 메모리 인프라를 관리하고 모니터링합니다.

# List all memory stores
stores_list = list(project_client.beta.memory_stores.list())

print(f"Found {len(stores_list)} memory stores")
for store in stores_list:
    print(f"- {store.name} ({store.description})")

에이전트 도구를 통해 메모리 사용

메모리 저장소를 만든 후 프롬프트 에이전트에 메모리 검색 도구를 연결할 수 있습니다. 이 도구를 사용하면 에이전트가 대화 중에 메모리 저장소에서 읽고 쓸 수 있습니다. 적절한 scope 및 update_delay로 도구를 구성하여 메모리가 업데이트되는 방법과 시기를 제어합니다.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
# You can also use "{{$userId}}" to take the TID and OID of the request authentication header
scope = "user_123"

openai_client = project_client.get_openai_client()

# Create memory search tool
tool = MemorySearchPreviewTool(
    memory_store_name=memory_store_name,
    scope=scope,
    update_delay=1,  # Wait 1 second of inactivity before updating memories
    # In a real application, set this to a higher value like 300 (5 minutes, default)
)

# Create a prompt agent with memory search tool
agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5.2",
        instructions="You are a helpful assistant that answers general questions",
        tools=[tool],
    )
)

print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

대화 만들기

이제 대화를 만들고 에이전트 응답을 요청할 수 있습니다. 각 대화가 시작될 때 정적 메모리가 주입되어 에이전트가 즉각적이고 지속적인 컨텍스트를 유지하도록 합니다. 상황별 기억은 각 응답을 알리기 위해 최신 메시지를 기반으로 턴당 검색됩니다.

각 에이전트 응답 후 서비스는 내부적으로 호출 update_memories합니다. 그러나 장기 메모리에 대한 실제 쓰기는 update_delay 설정에 의해 디바운스됩니다. 업데이트가 예약되고 구성된 비활성 기간 후에만 완료됩니다.

import time

# Create a conversation with the agent with memory tool enabled
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Create an agent response to initial user message
response = openai_client.responses.create(
    input="I prefer dark roast coffee",
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {response.output_text}")

# After an inactivity in the conversation, memories will be extracted from the conversation and stored
print("Waiting for memories to be stored...")
time.sleep(65)

# Create a new conversation
new_conversation = openai_client.conversations.create()
print(f"Created new conversation (id: {new_conversation.id})")

# Create an agent response with stored memories
new_response = openai_client.responses.create(
    input="Please order my usual coffee",
    conversation=new_conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {new_response.output_text}")

API를 통해 추억 사용

메모리 저장소 API를 사용하여 메모리 저장소와 직접 상호 작용할 수 있습니다. 먼저 대화 콘텐츠의 추억을 메모리 저장소에 추가한 다음 관련 추억을 검색하여 에이전트 상호 작용에 대한 컨텍스트를 제공합니다.

메모리 저장소에 추억 추가

메모리 저장소에 대화 콘텐츠를 제공하여 추억을 추가합니다. 시스템은 메모리 추출 및 통합을 포함하여 데이터를 전처리하고 후처리하여 에이전트의 메모리를 최적화합니다. 이 장기 실행 작업은 약 1분 정도 걸릴 수 있습니다.

매개 변수를 지정하여 사용자 간에 메모리를 분할하는 방법을 결정합니다 scope . 메모리 범위를 특정 최종 사용자, 팀 또는 다른 식별자에 지정할 수 있습니다.

여러 대화 턴의 콘텐츠로 메모리 저장소를 업데이트하거나 이전 업데이트 작업 ID를 사용하여 각 턴 및 체인 업데이트 후에 업데이트할 수 있습니다.

# Continue from the previous Python snippets.
# Set scope to associate the memories with
scope = "user_123"

user_message = {
  "role": "user",
  "content": "I prefer dark roast coffee and usually drink it in the morning",
   "type": "message"
}

update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[user_message],  # Pass conversation items that you want to add to memory
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)

# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

# Extend the previous update with another update and more messages
new_message = {
    "role":"user", 
    "content":"I also like cappuccinos in the afternoon", 
    "type":"message"}

new_update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[new_message],
    previous_update_id=update_poller.update_id,  # Extend from previous update ID
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

메모리 저장소에서 추억 검색

추억을 검색하여 에이전트 상호 작용에 대한 관련 컨텍스트를 검색합니다. 메모리 저장소 이름과 범위를 지정하여 검색 범위를 좁힐 수 있습니다.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchOptions

# Search memories by a query
query_message = {"role": "user", "content": "What are my coffee preferences?", "type": "message"}

search_response = project_client.beta.memory_stores.search_memories(
    name=memory_store_name,
    scope=scope,
    items=[query_message],
    options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
    print(f"  - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")

정적 또는 상황별 메모리 검색

사용자 프로필 기억은 사용자의 메시지와 의미 체계 유사성에 따라 검색할 수 없는 경우가 많습니다. 각 대화의 시작 부분에 정적 기억을 삽입하고 상황별 기억을 사용하여 각 에이전트 응답을 생성하는 것이 좋습니다.

  • 정적 메모리를 불러오려면 search_memories와 함께 scope를 사용하고 items 또는 previous_search_id는 사용하지 마십시오. 그러면 범위와 연결된 사용자 프로필 메모리가 반환됩니다.

  • 상황별 기억을 검색하려면 최신 메시지로 설정된 상태에서 호출 search_memoriesitems 합니다. 이렇게 하면 지정된 항목과 가장 관련성이 큰 사용자 프로필 및 채팅 요약 추억을 모두 반환할 수 있습니다.

사용자 프로필 및 채팅 요약 메모리에 대한 자세한 내용은 메모리 유형을 참조하세요.

메모리 삭제

경고

메모리 저장소를 삭제하기 전에 종속 에이전트에 미치는 영향을 고려합니다. 메모리 저장소가 연결된 에이전트는 기록 컨텍스트에 액세스할 수 없게 될 수 있습니다.

기억은 메모리 저장소 내의 범위별로 구성됩니다. 특정 범위에 대한 메모리를 삭제하여 사용자별 데이터를 제거하거나 전체 메모리 저장소를 삭제하여 모든 범위에서 모든 메모리를 제거할 수 있습니다.

범위별 메모리 삭제

메모리 저장소 구조를 유지하면서 특정 사용자 또는 그룹 범위와 연결된 모든 메모리를 제거합니다. 이 작업을 사용하여 사용자 데이터 삭제 요청을 처리하거나 특정 사용자의 메모리를 다시 설정합니다.

# Delete memories for a specific scope
project_client.beta.memory_stores.delete_scope(
    name=memory_store_name,
    scope="user_123"
)

print(f"Deleted memories for scope: user_123")

메모리 저장소 삭제

모든 범위에서 전체 메모리 저장소 및 연결된 모든 메모리를 제거합니다. 이 작업은 되돌릴 수 없습니다.

# Delete the entire memory store
delete_response = project_client.beta.memory_stores.delete(memory_store_name)
print(f"Deleted memory store: {delete_response.deleted}")

모범 사례

  • 사용자별 액세스 제어 구현: 에이전트가 모든 사용자 간에 공유한 추억에 대한 액세스 권한을 부여하지 않습니다. 속성을 scope 사용하여 사용자별로 메모리 저장소를 분할합니다. 사용자 간에 공유하는 scope 경우 메모리 시스템에 개인 정보를 저장하지 않도록 지시하는 데 사용합니다 user_profile_details .

  • 인증된 사용자에게 범위를 매핑합니다. 메모리 검색 도구에서 범위를 지정하는 경우 인증 토큰(scope={{$userId}})에서 사용자에게 매핑되도록 설정합니다{tid}_{oid}. 이렇게 하면 메모리 검색이 자동으로 올바른 사용자를 대상으로 합니다.

  • 중요한 데이터 최소화 및 보호: 사용 사례에 필요한 것만 저장합니다. 개인 데이터, 건강 데이터 또는 기밀 비즈니스 입력과 같은 중요한 데이터를 저장해야 하는 경우 개인에게 다시 추적하는 데 사용할 수 있는 다른 콘텐츠를 수정하거나 제거합니다.

  • 개인 정보 보호 및 규정 준수 지원: 사용자에게 데이터에 액세스하고 삭제하는 옵션을 포함하여 투명도를 제공합니다. 모든 삭제를 변조 방지 감사 내역에 기록합니다. 시스템이 로컬 규정 준수 요구 사항 및 규정 표준을 준수하는지 확인합니다.

  • 데이터를 분할하고 메모리를 격리합니다 . 다중 에이전트 시스템에서 메모리를 논리적 및 운영적으로 분할합니다. 고객이 자신의 메모리 공간을 정의, 격리, 검사 및 삭제할 수 있습니다.

  • 메모리 사용량 모니터링: 토큰 사용량 및 메모리 작업을 추적하여 비용을 이해하고 성능을 최적화합니다.

문제 해결

문제 원인 해결 방법
인증 또는 권한 부여 오류로 요청이 실패합니다. ID 또는 프로젝트 관리 ID에는 필요한 역할이 없습니다. 인증 및 권한의 역할을 확인합니다. REST 호출의 경우 새 액세스 토큰을 생성하고 다시 시도합니다.
대화 후에는 기억이 나타나지 않습니다. 메모리 업데이트가 디버그되거나 여전히 처리 중입니다. 대기 시간을 늘리거나 즉시 처리를 트리거하도록 설정된 업데이트 API update_delay 를 0 호출합니다.
메모리 검색은 결과를 반환하지 않습니다. 이 값은 scope 메모리가 저장되었을 때 사용되는 범위와 일치하지 않습니다. 업데이트 및 검색에 동일한 범위를 사용합니다. 사용자에게 범위를 매핑하는 경우 안정적인 사용자 식별자를 사용합니다.
에이전트 응답은 저장된 메모리를 사용하지 않습니다. 에이전트가 메모리 검색 도구로 구성되지 않았거나 메모리 저장소 이름이 잘못되었습니다. 에이전트 정의에 도구가 memory_search 포함되어 있고 올바른 메모리 저장소 이름을 참조했는지 확인합니다.

관련 콘텐츠

  • Last updated on