관리되는 에이전트 메모리

Important

이 기능은 베타 버전으로 제공됩니다. 작업 영역 관리자는 미리 보기 페이지에서 이 기능에 대한 액세스를 제어할 수 있습니다. Azure Databricks 미리 보기 관리를 참조하세요.

관리되는 에이전트 메모리는 대화에서 에이전트에 장기 메모리를 제공합니다. Azure Databricks 인프라를 실행하고 각 범위의 기억을 격리하므로 스토리지 또는 분할을 직접 관리할 필요가 없습니다.

관리되는 메모리를 사용하여 에이전트는 다음을 수행할 수 있습니다.

사용자 기본 설정, 과거 결정 및 대화 간에 누적된 컨텍스트를 기억하세요.
Unity 카탈로그 거버넌스를 사용하여 해당 지식을 보호합니다.
에이전트 및 프로젝트에서 메모리를 공유합니다.
시간이 지남에 따라 정확성과 효율성을 향상시킵니다.

Requirements

Unity 카탈로그를 사용하도록 설정된 Databricks 작업 영역입니다.
CREATE MEMORY STORE 메모리 저장소를 만드는 부모 스키마에 대한 권한입니다.

관리되는 메모리 작동 방식

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

메모리 저장소는 메모리 항목의 컨테이너 역할을 하는 Unity 카탈로그 보안 개체입니다. 메모리 저장소는 다른 Unity 카탈로그 자산과 동일한 거버넌스, 액세스 제어 및 계보를 상속합니다.
메모리 항목은 메모리 저장소 내에 저장된 개별 콘텐츠 조각입니다. 각 항목은 범위 및 경로로 식별됩니다. 범위는 항목이 속한 메모리를 결정하며, 경로는 파일 경로(예 /memories/preferences.md: )와 유사하게 범위 내에서 항목을 구성합니다.

Scope

범위는 메모리를 한 사용자에게 개인적으로 설정하거나 그룹 간에 공유하는 방법입니다. 애플리케이션은 모든 읽기와 쓰기에 범위를 설정하고, 검색은 범위가 일치하는 항목만 반환합니다. 에이전트가 기억해야 할 전략을 선택하세요:

각 사용자별 개인 메모리: 범위를 검증된 최종 사용자 신원으로 설정하세요. 각 사용자는 자신만의 파티션을 가지며 자신의 항목만 볼 수 있습니다. 이 값 user_client 은 최종 사용자의 ID를 대신 해석해 줍니다.
- 예시: 지원 상담원은 한 사용자의 통신 선호도와 과거 티켓을 기억합니다.
그룹을 위한 공유 기억: 조직, 팀, 프로젝트 ID 등 원하는 고정 키로 범위를 설정하세요. 모든 사용자는 같은 기억을 읽고 씁니다.
- 예시: 팀 에이전트는 회사 용어와 내부 정책의 공유 용어집을 기억합니다.
다른 무언가로 나눠진 기억: 세입자 ID나 user_id:project 합성 데이터와 같은 본인의 값으로 범위를 만드세요.
- 예시: 멀티 테넌트 앱은 각 고객의 메모리를 분리하거나, 프로젝트별로 단일 사용자의 메모리를 분리합니다.

한 명의 에이전트가 한 번의 대화에서 전략을 결합할 수 있습니다. 예를 들어, 동일한 요청 내에서 사용자의 개인 메모리와 공유 팀 메모리를 읽을 수 있습니다.

애플리케이션 코드에서 요청이 조작할 수 없는 신뢰할 수 있는 호출자 컨텍스트에서 범위를 설정하세요: 사용자별 메모리는 OBO 토큰에서 검증된 최종 사용자 신원을, 공유 메모리는 신뢰할 수 있는 테넌트, 팀, 프로젝트 키입니다. 모델이 선택하게 두지 마세요. 스코프 전략이 최종 사용자 신원에 의존한다면, 공유 스코프로 되돌아가기보다는 해당 신원이 없는 요청을 거부하세요. 이 스킬이managed-memory 이 세팅을 안내해 줍니다.

Scope는 메모리를 분리하지만, 스토어 접근 권한을 부여하지는 않습니다. 발신자는 여전히 전화를 열 권한이 필요합니다 READ MEMORY STOREWRITE MEMORY STORE . 메모리 접근 제어를 참조하세요.

Warning

범위는 사용자 간의 격리 경계이지만, 접근 제어는 아닙니다. 앱 서비스 주체는 모든 범위를 읽을 수 있으니, 자격 증명을 적절히 보호하세요.

요원이 저장하고 회상하는 것들

관리형 메모리는 메모리 저장소와 읽기 및 쓰기 항목을 위한 API를 제공합니다. 애플리케이션은 에이전트가 무엇을 저장할지, 언제 메모리를 가져올지, 그리고 결과를 어떻게 사용할지 통제합니다.

에이전트의 시스템 프롬프트에서 이 동작을 정의하세요: 어떤 내구성 있는 정보를 저장하고 언제 복구할지 지시하세요. managed-memory 스킬과 템플릿은 이 시스템 프롬프트를 MEMORY_INSTRUCTIONS라는 상수에 저장합니다. 범위는 신뢰할 수 있는 애플리케이션 코드에서 별도로 구성되며, 모델에서 선택하지 않습니다.

문구를 범위 전략에 맞추세요. 다음은 사용자당 전략의 예시입니다:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

관리되는 메모리 기능 시작하기

에이전트에 관리되는 메모리를 추가하는 가장 쉬운 방법은 Claude Code 기술입니다 managed-memory . 이 기술은 모든 설정을 처리하고 OpenAI 에이전트 SDK 및 LangGraph 둘 다에서 작동합니다.

다음 두 가지 방법 중 하나로 프로젝트에 기술을 가져옵니다.

템플릿에서 시작

이 스킬은 Databricks 앱 템플릿에 포함되어 있습니다. 에이전트 템플릿 중 하나에서 새 에이전트를 스캐폴드하고 아래에서 .claude/skills/managed-memory/기술을 찾습니다.

템플릿 리포지토리를 복제합니다.

git clone https://github.com/databricks/app-templates.git

app-templates를 둘러보고, 출발점으로 삼을 에이전트 템플릿을 선택하세요. 예를 들어 OpenAI 에이전트 SDK 템플릿을 사용하려면 다음을 수행합니다.
```
cd app-templates/agent-openai-agents-sdk
```
메모

"고급" 앱 템플릿의 경우 배포 후 앱 서비스 주체 Lakebase Postgres 권한을 부여해야 합니다. 그렇지 않으면 세션 설정에서 502 오류를 반환합니다.
기술이 프로젝트에 있으면 원하는 것을 설명하고 코딩 도우미가 나머지를 처리합니다.
Tip
```
Add Databricks managed long-term memory to my agent.
```

기존 프로젝트에 기술 추가

에이전트 프로젝트가 이미 있는 경우 기술을 추가합니다.

기술 디렉터리가 없는 경우 다음을 만듭니다.
```
mkdir -p .claude/skills/managed-memory
```
SKILL.md에서 managed-memory 파일을 다운로드하여 에 저장합니다.
기술이 프로젝트에 있으면 원하는 것을 설명하고 코딩 도우미가 나머지를 처리합니다.
Tip
```
Add Databricks managed long-term memory to my agent.
```

수동으로 메모리 저장소 만들기 및 사용

이 섹션에서는 Claude Code 기술 없이 managed-memory 메모리 저장소를 만들고 사용하는 방법을 보여 줍니다.

다음 예제에서는 사용자의 기본 설정을 저장하고 이후 대화에서 검색하는 고객 지원 에이전트에 대한 관리되는 메모리를 설정합니다.

Databricks CLI를 사용하여 API를 호출하는 OAuth 토큰을 생성합니다.
```
databricks auth login --host ${DATABRICKS_HOST}
databricks auth token
```

에이전트의 추억을 보관할 메모리 저장소를 만듭니다.

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support_agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Long-term memory for the customer support agent"
  }'

에이전트가 사용자에 대해 학습한 후 메모리 항목을 작성합니다. scope는 항목을 단일 사용자별로 분할합니다. 전체 메모리 텍스트에는 contents 필드를 사용하고, 검색을 개선하는 짧은 요약에는 description를 사용하세요:

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
    "description": "User 123 communication preferences and account details"
  }'

이후 대화에서 해당 사용자의 메모리 항목을 검색하여 에이전트가 학습한 내용을 검색합니다.

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-123",
    "query": "communication preferences"
  }'

엔드포인트, 요청 필드 및 응답 필드를 포함한 전체 REST API는 메모리 API 참조를 참조하세요.

대화를 사용하여 에이전트에 메모리 추가

위의 REST 워크플로는 메모리 저장소 및 항목 API를 직접 호출합니다. Azure Databricks 모델 서빙 엔드포인트에서 에이전트를 구축할 때는, 대신 SDK의 OpenAI 호환 클라이언트를 사용하여 메모리 저장소를 databricks-openai에 연결하세요.

대화는 메모리 저장소에서 지원되고 단일 범위에 고정된 OpenAI 호환 대화 상태(메시지 및 도구 호출의 실행 기록)입니다. 여러 요청에 걸쳐 같은 대화를 재사용해 에이전트가 이전 턴을 기억할 수 있게 합니다.

기존 메모리 저장소 및 범위를 새 대화에 바인딩합니다. memory_store.name 는 저장소의 세 가지 수준 이름이며 scope , 일반적으로 최종 사용자가 대화의 상태를 분할합니다.

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

workspace_client = WorkspaceClient()
user_id = str(workspace_client.current_user.me().id)

client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)

conversation = client.conversations.create(
    extra_body={
        "memory_store": {"name": "main.default.support_agent_memory"},
        "scope": {"kind": "user", "value": user_id},
    },
)

대화 ID를 responses.create에 전달합니다. 에이전트는 해당 범위 아래의 바인딩된 메모리 저장소에서 대화의 상태를 읽고 씁니다.

response = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
    stream=True,
)

for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

에이전트가 이전 턴을 기억하게 되도록 이후 요청에서 동일한 대화 ID를 다시 사용합니다. 턴당 새 대화를 만들지 마세요.

followup = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
    stream=True,
)

for event in followup:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

대화 엔드포인트 및 요청 필드에 대해서는 대화 API를 참조하세요.

메모리 접근 제어

메모리 저장소는 Unity 카탈로그 보안 개체입니다. 다음 권한은 접근을 제어합니다:

특권	적용 대상	설명
`CREATE MEMORY STORE`	부모 스키마	스키마 아래에 새 메모리 저장소를 만듭니다.
`READ MEMORY STORE`	메모리 저장소	메모리 저장소의 메타데이터 및 해당 항목을 읽습니다.
`WRITE MEMORY STORE`	메모리 저장소	저장소에서 메모리 항목을 만들고, 업데이트하고, 삭제합니다.
`MANAGE`	메모리 저장소	메모리 저장소 자체를 업데이트하거나 삭제합니다. 다른 사용자에게 사용 권한을 부여합니다.
`USE SCHEMA`	부모 스키마	스키마에 메모리 저장소를 나열합니다.

단기 메모리 구현

메모리 엔트리 API는 에이전트가 사용할 수 있는 도구 형태로 장기 메모리를 제공합니다. 세션 내에서 에이전트에 관리형 단기 메모리를 제공하려면 Databricks는 메모리 저장소를 대화에 연결하는 것을 권장합니다. 또한 다음을 할 수 있습니다:

OpenAI session= 매개 변수 또는 LangGraph 검사점과 같은 에이전트 프레임워크의 세션 메모리를 유지합니다.
대화 기록 저장소에 자체 관리 에이전트 메모리 를 사용합니다.

보안 권장 사항

Azure Databricks 관리되는 저장소, 암호화, 격리 기본 형식 및 감사 내역을 제공합니다. 앱 개발자인 Databricks는 다음을 권장합니다.

프로젝트별 또는 계정별 메모리와 같이 의도적으로 분할해야 하는 이유가 없는 경우 사용자별 범위 기본값(user_client)을 사용합니다.
최소 권한을 부여하세요: 에이전트의 서비스 주체에만 WRITE MEMORY STORE 권한이 필요합니다. 권한은 필요한 범위로만 READ MEMORY STORE 부여하고, 개별 사용자 또는 대규모 그룹에는 광범위한 권한을 부여하지 마세요.
앱 서비스 주체 자격 증명 보호: 저장소의 데이터 평면에 대한 키입니다. 모든 고가용성 서비스 자격 증명처럼 처리합니다. 수명이 짧은 토큰을 사용하고, 로깅하지 말고, 앱에 SSRF 방어를 추가합니다.

Limitations

메모리 항목은 장기 메모리만 제공합니다. 단기 및 장기 메모리의 차이는 단기 및 장기 메모리를 참조하세요.
메모리 저장소 및 항목은 Unity 카탈로그 REST API를 통해서만 만들어지고 관리됩니다. 이러한 API에 대한 Python SDK가 없습니다. 에이전트의 메모리 저장소를 사용하려면 OpenAI 호환 클라이언트와의 대화에 연결합니다. 대화가 있는 에이전트에 메모리 추가를 참조하세요.

다음 단계

메모리 API 참조

피드백

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

Last updated on 2026-08-19