에이전트 메모리 파이프라인

Important

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

기억 파이프라인은 에이전트의 과거 대화에서 장기 기억을 쌓아갑니다. 세션 저장소에서 대화 기록을 읽고, 사실, 선호도, 절차 등 장기 기억을 메모리 저장소에 추출해 저장합니다. 에이전트는 이후 대화에서 그 기억들을 자신이 저장한 기억을 떠올리는 것과 같은 방식으로 떠올립니다.

대화 중에 기억을 저장하는 에이전트는 해당 대화의 맥락만을 고려해 한 번에 한 대화씩 기억을 저장합니다. 수많은 대화를 거치면서, 에이전트의 메모리는 겹치고 상충하는 항목들을 수집하고, 에이전트가 저장할 생각을 못 한 사실들은 메모리에 도달하지 못한다. 메모리 파이프라인은 사후에 작동하며, 모든 행위자의 대화와 기존 메모리를 모두 볼 수 있어 에이전트가 놓친 내용을 캡처하고 메모리를 통합할 수 있습니다.

메모리 파이프라인을 사용하려는 경우:

기억 작성 도구를 에이전트에게 추가하지 않고도 대화에서 장기 기억을 쌓으세요.
세션 저장소가 이미 보유한 대화 기록으로 메모리를 백필하세요.
겹치는 항목을 합치거나 큰 항목을 분할하여 시간이 지남에 따라 기억을 정리하세요.

메모리 파이프라인은 단독으로 사용할 수도 있고, 대화 중에 에이전트가 호출하는 메모리 도구 와 함께 사용할 수도 있습니다.

Note

메모리 파이프라인 실행은 작업에는 서버 없는 일반 컴퓨트 가격 책정을, 모델 호출에는 Foundation Model Serving 가격 책정을 사용합니다.

Requirements

에이전트의 대화를 저장하는 세션 저장소 와 기억을 기록하는 메모리 저장소 가 있습니다.
파이프라인을 생성하는 ID에 대한 두 저장소 접근 권한, 메모리 저장소 데이터베이스에 테이블을 생성할 권한도 포함됩니다. 파이프라인 실행에는 해당 ID를 사용합니다.
파이프라인이 증류에 사용하는 모델을 쿼리할 수 있는 권한. 이 기능이 없으면 파이프라인의 실행이 실패합니다.
CLI를 사용하려면 databricks-agentbricks 0.6.0 이상을 설치하세요. 또한 어떤 언어에서든 REST API를 직접 호출할 수도 있습니다.

메모리 파이프라인의 작동 원리

메모리 파이프라인은 한 세션 저장소를 하나의 메모리 저장소에 연결하는 에이전트 메모리 자원입니다. Lakeflow 파이프라인과는 관련이 없습니다. 세션 저장소는 여러 메모리 저장소를 공급할 수 있지만, 세션 저장소와 메모리 저장소 쌍은 단 하나의 파이프라인만 가질 수 있습니다.

Unity 게이트웨이를 통한 모델 호출: 파이프라인은 Unity 게이트웨이를 통해 증류 모델을 호출합니다.
모델 선택: 파이프라인을 만들 때 모델을 선택하고 나중에 변경할 수 있습니다. 하나를 선택하지 않으면 파이프라인이 기본 모델을 사용합니다.
서버리스 컴퓨트에서의 수동 또는 예약 실행: 직접 실행을 시작하거나, 파이프라인을 약 24시간마다 일정에 따라 실행하도록 설정하세요. 어쨌든 각 실행은 파이프라인을 만든 아이덴티티를 사용하여 서버리스 컴퓨트에서 작업으로 실행됩니다.

파이프라인의 각 실행은 세션 저장소 내 모든 액터를 개별적으로 처리합니다:

요약: 파이프라인은 액터의 새로운 대화를 읽고 LLM을 사용해 그 대화에서 견고한 사실을 추출합니다.
병합: 파이프라인은 새로운 사실을 중복 해제하여 메모리 저장소 내 동일한 actor_id 아래 주제별 메모리 항목으로 병합합니다.
유지: 파이프라인은 액터의 메모리를 재구성합니다. 중복되는 항목을 병합하고, 너무 커지는 항목은 분할합니다.

메모리 파이프라인 실행은 각 액터 ID에 대해 체크포인트를 유지합니다. 런은 액터의 마지막 성공 실행 이후 모든 세션을 처리하므로, 첫 런은 그 액터의 전체 이력을 처리합니다. 한 액터의 실행이 실패하면 다른 액터들에 대해서는 계속 진행되며, 다음 실행은 실패한 액터를 체크포인트에서 다시 시도합니다.

actor_id가 두 매장을 연결합니다. 파이프라인은 세션 스토어에 세션이 있는 액터만 처리하며, 각 액터의 기억을 해당 액터의 세션이 사용하는 동일한 actor_id 아래에 기록합니다. 기본적으로 파이프라인은 런을 시작할 때만 실행됩니다. 예약된 일정에 따라 실행할 수도 있습니다.

Note

유지보수는 에이전트가 직접 저장한 항목을 포함해 액터의 모든 메모리 항목에 적용됩니다. 파이프라인은 처리하는 actor_id 아래의 모든 항목을 다시 쓰거나, 병합하거나, 분할하거나, 삭제할 수 있습니다.

파이프라인이 유지하는 항목

파이프라인은 대화에서 개별적이고 오래 유지되는 사실을 추출합니다. 이 시스템은 다음을 유지하도록 설계되었습니다:

사용자가 명확히 말하는 사실과 그들이 표현하는 선호를, 대화에서 말한 내용을 넘어 추론하지 않고 포함하는 것.
수익 수치에 어떤 출처를 사용할지와 같은 수정 및 명시적 피드백.
권위 있는 출처, 지표 정의, 용어, 팀 관습과 같은 지속적인 도메인 지식뿐만 아니라 워크플로우와 진행 중인 프로젝트도 포함됩니다.

건너뛰도록 설계되었습니다:

테이블의 현재 행 수 등 시간이 지남에 따라 변하는 라이브 소스의 값들. 대신 값을 찾거나 계산하는 방법을 기록합니다.
에이전트가 도구로 조회할 수 있는 테이블 스키마 같은 세부 정보입니다.
비밀번호, API 키, 토큰과 같은 비밀 정보들입니다.

Get started

이 예시들은 지원 에이전트의 세션과 메모리 저장소를 위한 메모리 파이프라인을 생성하고, 실행을 시작하며, 결과를 확인합니다. 각 스토어를 ID, 스토어를 생성할 때 선택한 식별자, 또는 리소스 이름(예: memory-stores/support-agent-memory.)으로 식별하세요. 프로젝트에 맞는 클라이언트를 선택하세요.

에이전트 브릭스

Databricks CLI는 저장된 Databricks CLI 프로필을 사용해 인증합니다.

에이전트 브릭 CLI를 설치하거나 0.6.0 이상으로 업그레이드하세요:
```
pip install --upgrade databricks-agentbricks
```
support-agent-sessions 세션 저장소를 support-agent-memory 메모리 저장소로 압축하는 파이프라인을 만드세요. --model은(는) 선택 사항입니다. 만약 이를 생략하면 파이프라인은 기본 모델을 사용합니다:
```
agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --model system.ai.claude-sonnet-5
```
명령어는 파이프라인의 리소스 이름을 memory-pipelines/<pipeline-id> 형식으로 반환합니다.
파이프라인 실행을 시작하세요:
```
agentbricks memory pipeline run <pipeline-id>
```
명령어는 memory-pipelines/<pipeline-id>/runs/<run-id> 형식의 런 리소스 이름과 해당 RUNNING 상태를 반환합니다.

CLI는 실행 결과를 보고하지 않습니다. 확인하려면 DATABRICKS_HOST를 작업 공간 호스트네임으로 설정하고, OAuth 토큰을 생성한 뒤 REST API를 호출하세요:

export DATABRICKS_TOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)
curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

REST API

CLI는 /api/2.0/agents/memory-pipelines에서 REST API를 호출합니다. 어떤 언어에서든 직접 호출할 수 있습니다.

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

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

support-agent-sessions에서 기억을 추출해 support-agent-memory에 저장하는 파이프라인을 만드세요. dreamer_policy.model은(는) 선택 사항입니다. 만약 이를 생략하면 파이프라인은 기본 모델을 사용합니다:
```
curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"model": "system.ai.claude-sonnet-5"}}'
```
응답의 name 필드에는 memory-pipelines/<pipeline-id> 형식의 파이프라인 리소스 이름이 들어 있습니다.

파이프라인 실행을 시작하세요:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/run" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{}'

응답의 name 필드에는 런의 리소스 이름이 memory-pipelines/<pipeline-id>/runs/<run-id> 형식으로 들어 있습니다.

실행 결과를 확인하세요:

curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

실행이 성공하면, 에이전트는 메모리 저장소의 목록과 검색 작업을 통해 새로운 기억을 불러올 수 있습니다. 에이전트 메모리를 참조하세요.

파이프라인 실행을 모니터링하기

run의 state는 다음 중 하나입니다:

주	Meaning
`RUNNING`	실행은 대기 중이거나 진행 중입니다.
`SUCCEEDED`	이 실행은 모든 액터를 성공적으로 처리했습니다.
`FAILED`	실행이 하나 이상의 액터에서 오류와 함께 종료되었습니다. `error` 필드는 실패를 설명합니다.
`CANCELLED`	이 실행은 완료되기 전에 취소되었습니다.

지침이 있는 지식 증류 제어

지침은 파이프라인에 무엇을 보관하고 어떻게 정리해야 하는지 알려줍니다. 파이프라인은 모든 단계에서 이를 적용합니다. 다음과 같은 고수준 안내를 위해 활용하세요:

고객 선호도와 계정 세부 정보 같은 집중해야 할 주제들.
건너뛸 콘텐츠(예: 일회성 문제 해결 단계).
항목을 정리할 경로

레이아웃 지침이 없으면 파이프라인은 스토어의 기존 항목 레이아웃을 따르거나, 스토어가 비어 있을 때 주제별 레이아웃을 도출합니다. 기존 항목의 이름을 새 레이아웃에 맞게 변경하지 않습니다. 특정 항목을 변경하려면 지침으로 편집하지 말고 메모리 저장소의 업데이트 연산으로 편집하세요.

파이프라인을 만들 때 지침을 설정하고 나중에 변경할 수 있습니다. 다음 런에서는 새로운 명령어를 사용합니다.

에이전트 브릭스

파이프라인을 생성할 때 지침을 설정하려면 --instructions을(를) 전달하세요:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --instructions "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."

UTF-8 파일에서 긴 명령어를 불러오려면 대신 --instructions @<path-to-file>를 전달하세요.

기존 파이프라인의 지침을 변경하려면 다음을 실행하세요:

agentbricks memory pipeline update <pipeline-id> \
  --instructions "Keep only durable customer preferences."

REST API

REST API에서 파이프라인의 dreamer_policy 객체는 증류 설정을 포함합니다: instructions, trigger, 그리고 model. 파이프라인을 생성할 때 지침을 설정하려면 dreamer_policy.instructions에 포함하세요:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"instructions": "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."}}'

기존 파이프라인의 지침을 변경하려면 dreamer_policy.instructions을(를) 업데이트하세요:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.instructions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"instructions": "Keep only durable customer preferences."}}'

일정에 따라 파이프라인을 실행하세요

예약된 파이프라인은 약 24시간마다 자동으로 실행됩니다. 파이프라인을 만들 때 트리거를 설정할 수 있고, 나중에 변경할 수도 있습니다. 스케줄러는 첫 번째 예약된 실행 시작 시점을 선택합니다. 기존 대화를 바로 추출하려면 수동으로 실행을 시작하세요.

에이전트 브릭스

예약된 파이프라인을 생성하려면 --trigger scheduled을 전달하세요. 기본값은 다음과 같습니다.--trigger manual

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --trigger scheduled

기존 파이프라인의 트리거를 변경하려면 다음을 실행하세요:

agentbricks memory pipeline update <pipeline-id> --trigger scheduled

예약된 파이프라인이 있다면 일시정지할 수 있습니다:

agentbricks memory pipeline pause <pipeline-id>

예약된 실행을 다시 시작하려면 해당 실행을 재개하세요:

agentbricks memory pipeline resume <pipeline-id>

REST API

예약된 파이프라인을 생성하려면 SCHEDULED을(를) dreamer_policy.trigger(으)로 설정하세요:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"trigger": "SCHEDULED"}}'

기존 파이프라인의 트리거를 변경하려면 dreamer_policy.trigger를 SCHEDULED 또는 MANUAL_ONLY로 업데이트하세요:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.trigger" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"trigger": "SCHEDULED"}}'

다른 실행이 진행 중이 아닌 한, 예약된 파이프라인의 실행(run)을 수동으로 시작할 수도 있습니다.

파이프라인 관리

다음 명령어들은 파이프라인을 나열, 검사, 업데이트, 삭제합니다. 각 CLI 명령어는 파이프라인 ID 또는 전체 memory-pipelines/<pipeline-id> 리소스 이름 중 하나를 받아들입니다.

작업	Agent Bricks CLI	REST API
파이프라인 목록	`agentbricks memory pipeline list`	`GET /api/2.0/agents/memory-pipelines`
파이프라인을 생성하세요	`agentbricks memory pipeline get <pipeline-id>`	`GET /api/2.0/agents/memory-pipelines/<pipeline-id>`
파이프라인 업데이트	`agentbricks memory pipeline update <pipeline-id>`와 함께 `--display-name`, `--model`, `--trigger`, 또는 `--instructions`	`update_mask`이(가) `display_name`, `dreamer_policy.model`, `dreamer_policy.trigger` 또는 `dreamer_policy.instructions`인 `PATCH /api/2.0/agents/memory-pipelines/<pipeline-id>`
파이프라인 삭제	`agentbricks memory pipeline delete <pipeline-id>`	`DELETE /api/2.0/agents/memory-pipelines/<pipeline-id>`

만약 표시 이름을 설정하지 않으면, 파이프라인은 세션 저장소와 메모리 저장소 이름을 기반으로 표시명을 받습니다. 파이프라인을 기본 모델로 전환하려면 모델을 빈 값으로 업데이트하세요(예: --model ""). 모델 및 명령어 변경은 다음 실행 단계에 적용됩니다.

파이프라인을 삭제하면 연결된 작업이 삭제되고 향후 런이 중단됩니다. 이미 진행 중인 실행은 끝까지 계속됩니다. 파이프라인이 이미 작성한 메모리 항목은 메모리 저장소에 남아 있습니다.

Limitations

세션 저장소와 메모리 저장소는 파이프라인을 만들 때 고정됩니다. 둘 중 하나를 변경하려면 파이프라인을 삭제하고 새로 생성하세요. 새 파이프라인은 기존 파이프라인의 체크포인트를 재사용하지 않기 때문에, 첫 실행은 같은 스토어 쌍에 대해 각 액터의 전체 이력을 처리합니다.
파이프라인이 이미 같은 세션 저장소와 메모리 저장소를 연결한다면, 다른 것을 생성하면 ALREADY_EXISTS와 함께 실패합니다.
파이프라인은 한 번에 하나의 실행만 진행할 수 있습니다. 다른 실행이 진행 중일 때 새 실행을 시작하면 ABORTED 오류와 함께 실패합니다.
예약된 파이프라인은 약 24시간마다 운영됩니다. 다른 간격이나 크론 스케줄을 설정할 수 없습니다.
파이프라인은 세션 스토어에 세션이 있는 액터만 처리합니다. 세션이 없는 액터의 메모리 항목은 변경되지 않습니다.
만약 세션 스토어에 UUID 액터 ID를 가진 액터가 약 1,200명 이상이라면, 실행이 실패합니다. 직렬화된 액터 ID의 제한은 48 KiB이므로, ID가 짧을수록 더 많은 액터를 수용할 수 있습니다.

추가 리소스

피드백

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

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