관리되는 에이전트 메모리

Important

이 기능은 베타 버전으로 제공됩니다.

매니지드 에이전트 메모리는 상담원에게 지속적이고 장기적인 기억을 부여하여 대화 내내 지속됩니다. Azure Databricks는 Lakebase에 메모리를 저장하고 저장, 인덱싱, 의미 검색 등을 대신 관리해, 에이전트가 사용자가 데이터베이스를 운영하지 않고도 사용자 선호도, 과거 결정, 누적된 맥락을 기억할 수 있도록 합니다.

메모

미리보기 중에는 메모리 항목을 저장하는 Lakebase 인스턴스에 대한 요금이 청구됩니다. 관리 에이전트 메모리 자체에 대해서는 추가 요금이 적용되지 않습니다. 가격은 미리보기 진행에 따라 변경될 수 있습니다.

에이전트가 다음을 수행하도록 하려면 관리 메모리를 사용하세요:

사용자 선호도, 사실, 그리고 각기 다른 대화에서 결정들을 기억하세요.
상담원이 이전 세션에서 배운 내용을 바탕으로 응답을 개인화하세요.
에이전트와 프로젝트 간에 축적된 지식을 공유하세요.
시간이 지남에 따라 정확도와 효율성을 향상시킵니다.

관리 메모리는 어떤 프레임워크 기반의 에이전트와 함께 작동합니다. 단일 상호작용 내 단기 대화 기록을 위해서는 관리 상담원 세션을 사용하세요.

Requirements

AgentKit SDK를 사용하려면 Python 3.10 이상 버전을 설치하세요. AgentKit SDK는 아래 예시들이 사용하는 에이전트 API용 Databricks Python 클라이언트입니다. 또한 Python 요구사항 없이 어떤 언어에서든 REST API를 직접 호출할 수 있습니다.

관리되는 메모리 작동 방식

관리형 에이전트 메모리 자원 계층 구조: 메모리 저장소는 actor_id, 선택적 session_id, 경로로 식별되는 여러 메모리 항목과 내용 및 설명을 포함합니다.

관리되는 메모리에는 다음 두 가지 수준이 있습니다.

메모리 저장소는 에이전트의 메모리를 위한 작업 공간 범위 컨테이너입니다. 저장소를 생성하면 백업 Lakebase 저장소가 자동으로 프로비저딩됩니다. 스토어는 display_name(으)로 지정합니다.
메모리 항목은 저장소 내의 개별 콘텐츠 조각입니다. 각 항목은 자유 형식의 텍스트, 검색에 사용되는 짧은 텍스트contentdescription, 그리고 그것을 조직하고 분할하는 필드 집합을 가지고 있습니다:
- actor_id (필수): 메모리가 누구의 것인지, 예를 들어 최종 사용자 또는 다른 에이전트.
- session_id (선택): 메모리가 캡처된 세션을 기록하여 추적 및 출처 확인을 위해 저장합니다. 특정 세션에 묶이지 않은 메모리를 위해 설정하지 않은 상태로 두세요.
- path (필수): 액터 내 항목을 조직하는 파일 시스템과 유사한 경로, 예를 들어 /preferences/response-style.md.

한 항목은 session_id, path, actor_id의 조합으로 고유하게 식별됩니다.

검색

메모리를 두 가지 방법으로 검색합니다:

session_id 액터의 항목을, 선택적으로 path 또는 접두사로 필터링하여. 이를 사용해 에이전트가 아는 내용을 탐색하거나 인덱스를 렌더링하세요.
자연어 쿼리가 포함된 배우 항목을 검색하세요. 검색은 전체 텍스트(BM25) 관련성 점수로 순위를 매긴 가장 관련성 높은 항목을 반환합니다.

Get started

이 예시들은 지원 에이전트를 위해 관리 메모리를 설정합니다: 메모리 저장소를 생성하고 사용자의 선호도를 저장한 후 이후 대화에서 이를 호출합니다. 프로젝트에 맞는 클라이언트를 선택하세요. 메모리 저장소 display_name 는 3자에서 56자까지여야 하며, 소문자로 시작해 글자 또는 숫자로 끝나야 하며, 소문자, 숫자, 하이픈만 포함해야 합니다.

AgentKit SDK

AgentKit SDK는 패키지에 배포 databricks-agentbricks 된 Databricks Python 클라이언트로, 에이전트 API를 지원합니다. Databricks SDK로 인증합니다 WorkspaceClient.

AgentKit SDK 설치:
```
pip install databricks-agentbricks
```

에이전트를 위한 메모리 저장소를 만드세요. AgentKitClient이(가) 회원님의 WorkspaceClient 자격 증명으로 인증합니다:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

에이전트가 사용자에 대해 지속 가능한 정보를 알게 된 후 기억을 저장하세요. actor_id 이 메모리가 누구의 것인지 를 사용하며, path 해당 액터 description 내에서 이를 조직하고 검색을 향상시킵니다:
```
memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)
```

자연어 검색으로 이후 대화에서 사용자의 기억을 떠올리세요:

results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

REST API

클라이언트는 /api/2.0/agents/memory-stores 아래의 REST API를 호출합니다. Python 외의 언어에 대해 직접 호출하세요.

Databricks CLI로 OAuth 토큰을 생성하세요:

databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

에이전트를 위한 메모리 저장소를 만드세요:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

사용자를 위한 메모리 항목을 저장하세요. actor_id는 이것이 누구의 기억인지 나타내고, path는 이를 정리하며, description는 검색을 향상합니다:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

자연어 검색으로 사용자의 기억을 되살리세요:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

에이전트에게 메모리 도구를 주세요

에이전트가 언제 저장하고 메모리를 호출할지 결정할 수 있도록 하기 위해, 클라이언트 작업을 도구로 감싸고 시스템 프롬프트에서 언제 사용할지 에이전트에게 지시합니다. 검증된 최종 사용자 신원을 기반으로 신뢰할 수 있는 애플리케이션 코드에서 actor_id를 설정하세요. 모델이 누구의 메모리를 읽거나 쓸지 선택하게 하지 마세요.

다음 예시는 Get started의 AgentKit SDK memory_store 를 OpenAI 에이전트 SDK용 도구로 포장하고 있습니다.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

같은 패턴이 Claude Agent SDK와 다른 프레임워크에서도 작동합니다: 저장소의 검색 및 추가 작업을 프레임워크의 도구 유형으로 랩핑합니다.

파티션 및 보안 메모리

가게 안에서 actor_id로 각 기억이 누구의 것인지 구분합니다. 모든 목록과 검색은 단일 actor_id, 에 맞게 조정되므로, 에이전트가 기억해야 할 사항에 맞는 전략을 선택하세요:

각 사용자별 개인 메모리: 검증된 최종 사용자 신원으로 설정 actor_id . 각 사용자는 자신만의 파티션을 가지고 있으며, 에이전트는 해당 사용자의 항목만 호출합니다.
- 예시: 지원 상담원은 한 사용자의 통신 선호도와 과거 티켓을 기억합니다.
그룹의 공유 메모리: 팀, 프로젝트, 조직 ID 등 원하는 고정 키로 설정 actor_id 하세요. 모두가 같은 기억을 읽고 씁니다.
- 예시: 팀 에이전트가 회사 용어와 내부 관례의 공유 용어집을 기억합니다.
다른 기준으로 분할한 메모리: 테넌트 ID나 actor_id 복합체와 같은 자체 값을 사용해 user:project를 빌드하세요.
- 예시: 멀티 테넌트 앱은 각 고객의 사용자가 서로 격리되도록 설정 actor_id{tenant}:{user} 합니다.

애플리케이션 코드에서 신뢰할 수 있는 호출자 컨텍스트를 사용해 actor_id를 설정하세요. 사용자별 메모리에는 검증된 최종 사용자 ID를, 공유 메모리에는 신뢰할 수 있는 팀 또는 프로젝트 키를 사용하세요. 모델이 선택하게 두지 마세요. 전략이 최종 사용자 ID에 의존하는 경우, 해당 ID가 없는 요청은 공유 actor_id로 대체하지 말고 거부하세요.

Warning

actor_id 기억을 분리하지만, 접근 제어는 아닙니다. 관리형 메모리 저장소는 작업 공간 범위가 지정되어 있어, 저장소에 도달할 수 있는 모든 주체가 모든 액터의 모든 항목을 읽고 쓸 수 있습니다. 가게가 보안 경계이지, 배우가 아니에요. 테넌트나 사용자 간 엄격한 격리를 위해 경계별로 별도의 메모리 저장소를 생성하세요.

에이전트의 서비스 프린시펄과 같은 다른 프린시펄이 스토어를 사용할 수 있게 하려면, 스토어의 grant-permission 연산(memory_store.grant_permission(principal_id) AgentKit SDK에서)으로 스토어에 접근을 부여하세요.

Limitations

관리 기억은 장기 기억만을 제공합니다. 단기 대화 기록은 관리 에이전트 세션을 참조하세요.
검색은 관련성 순위에 따른 전체 텍스트(BM25) 연산으로, 최대 100개의 항목으로 구성된 상위 N개 결과 세트를 반환합니다. 페이지네이션이나 벡터 유사도 검색을 지원하지 않습니다.
출입 통제는 매장 단위에서 시행됩니다. 항목별 및 액터별 접근 제어는 제공되지 않습니다.
상점은 display_name 생성 후 불변입니다. description 업데이트만 가능합니다.

다음 단계

피드백

이 페이지가 도움이 되었나요?

2026-10-06 에 마지막으로 업데이트됨