독립형 메모리 서비스 사용

메모리 전용 프로젝트 만듭니다.

다음 명령을 실행하여 메모리 전용 프로젝트 스캐폴딩합니다. "My Project"을 프로젝트 이름으로 바꿉니다.

agentengine create --memory-only --name "My Project"

이 명령은 agent.yaml 파일 이나 작업 공간 없이 project-config.yaml 파일 만 포함하는 프로젝트 디렉토리 생성합니다.

플랫폼에서 프로젝트 생성하고 선택합니다.

1. 다음 명령어를 실행하여 프로젝트 등록합니다. 이 명령은 새 프로젝트 ID 인쇄합니다.

   agentengine project create "My Project"

2. 새 프로젝트 활성으로 선택합니다. <project-id>을 이전 명령으로 출력된 프로젝트 ID 로 바꿉니다.

   agentengine auth login --project-id <project-id>

메모리 설정을 구성합니다.

1. project-config.yaml 파일 열고 memory: 차단 아래에 시크릿 이름과 추출 제공자 설정하다 .

2. 다음 명령을 실행하여 프로젝트 에 필요한 시크릿을 설정하다 .

   agentengine secret set MONGODB_URI --value "<value>" --project-id <project-id>
   agentengine secret set VOYAGE_API_KEY --value "<value>" --project-id <project-id>
   agentengine secret set ANTHROPIC_API_KEY --value "<value>" --project-id <project-id>

   다음 자리 표시자 값을 바꿉니다.

   • <value>: 시크릿의 값입니다.

     • MONGODB_URI: Atlas cluster 의 연결 문자열입니다.

     • VOYAGE_API_KEY: 사용자의 Voyage AI 키입니다.

     • ANTHROPIC_API_KEY: LLM 제공자 키입니다.

   • <project-id>: agentengine project create 명령이 반환한 프로젝트 객체 ID . 메모리 전용 워크플로에는 agents.yaml 파일 이 포함되어 있지 않으므로 이 플래그가 필요합니다.

   다른 제공자 사용하는 경우 ANTHROPIC_API_KEY을 LLM 제공자 의 키 이름으로 바꿉니다.

3. 메모리 구성을 저장합니다.

   agentengine memory configure

메모리 서버 프로비저닝합니다.

메모리 런타임을 시작하고 준비가 될 때까지 기다립니다.

agentengine memory apply --wait

서비스 계정을 만들고 액세스 토큰을 조회 .

1. 다음 명령어를 실행하여 프로젝트 에 대한 서비스 계정을 만듭니다.

   agentengine service-account create memory-service --project-id <project-id> --role PROJECT_OWNER

   <project-id> 자리 표시자를 프로젝트 ID 로 바꿉니다. 명령 출력에서 클라이언트 ID 와 클라이언트 시크릿을 저장합니다. Atlas Agent Engine은 클라이언트 시크릿을 한 번만 표시합니다.

2. 다음 명령을 실행하여 클라이언트 ID 와 클라이언트 시크릿을 액세스 토큰으로 교환합니다.

   export ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error \
     --user <client-id> \
     --data grant_type=client_credentials \
     "https://agentengine.mongodb.com/api/v1/oauth/token" | jq -er .access_token)

   <client-id> 자리 표시자를 클라이언트 ID 로 바꿉니다. curl는 클라이언트 시크릿을 에코하지 않고 입력하라는 메시지를 표시합니다.

   팁

   액세스 토큰은 1시간 동안 유효합니다. 현재 토큰이 만료되기 전에 새 토큰을 요청하세요.

Python SDK를 설치합니다.

이전 단계에서 내보낸 액세스 토큰을 사용하여 플랫폼의 비공개 레지스트리에서 agent-engine-sdk-memory 패키지 설치합니다.

pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

uv pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

URL username:password 형식을 사용합니다. 레지스트리가 비밀번호 필드 에 있는 액세스 토큰만 사용하여 인증하기 때문에 ignore은(는) 자리 표시 사용자 이름 입니다. $ACCESS_TOKEN는 이전 단계에서 내보낸 액세스 토큰으로 확인됩니다.

대화 컨텍스트를 기록하고 조회 .

애플리케이션 에서 다음 코드를 추가하여 클라이언트 생성하고, 사용자 ID를 바인딩하고, 회전이 발생할 때 기록 , 이후 대화에서 관련 컨텍스트를 조회 .

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
)
# Create the client using your access token.
memory = Memory(service_account_token="<your-access-token>")
# Bind the user and session for this conversation.
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
# Record turns as they happen.
chat.record_turn(
    role="user",
    content="I always fly out of Boston.",
)
chat.record_turn(
    role="assistant",
    content="Got it, Boston is saved as your home airport.",
)
# In a later conversation, recall what matters.
later = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_456",
    )
)
context = later.build_context(
    query="Where should the flight book from?"
)
hits = later.search("home airport", top_k=5)

로컬 메모리 프로젝트 스캐폴딩합니다.

다음 명령을 실행하여 로컬 개발을 위한 메모리 전용 프로젝트 스캐폴딩합니다. "My Project"을(를) 프로젝트 이름으로 바꿉니다.

agentengine create --memory-only --name "My Project"

이 명령은 memory_only을(를) true(으)로 설정하고 메모리 구성 스키마 지정하는 project-config.yaml 파일 작성합니다.

이 명령은 agent.yaml 파일, agents/ 디렉토리 또는 에이전트 런타임 코드를 생성하지 않습니다. --memory-only 플래그와 --template, --llm, --memory 또는 --open-egress 플래그를 결합할 수 없습니다.

환경 변수를 구성합니다.

프로젝트 디렉토리 에 .env 파일 생성한 후, 파일 에서 다음 변수를 설정하다 .

• VOYAGE_API_KEY:Voyage AI 임베딩에 필요

• LLM 제공자 키(예: ANTHROPIC_API_KEY): project-config.yaml에서 배경 추출이 활성화된 경우 필요

MONGODB_URI 변수를 설정하다 필요가 없습니다. agentengine dev up 명령은 번들 로컬 MongoDB 컨테이너 자동으로 프로비저닝하고 연결합니다. 대신 외부 MongoDB 인스턴스 사용하려면 이 변수를 설정하다 .

로컬 스택 시작합니다.

프로젝트 디렉토리 에서 다음 명령을 실행 로컬 메모리 스택 시작합니다.

agentengine dev up

메모리 전용 프로젝트 의 경우 이 명령은 다음 컨테이너만 시작합니다.

• mongodb: 로컬 Atlas 호환 MongoDB 인스턴스

• memory-server: 메모리 런타임 서비스

• oe: SDK가 연결하는 로컬 오케스트레이션 엔진 프록시

명령 출력에는 로컬 oe 및 memory-server 서비스에 대한 URL이 포함됩니다. 이후 단계에서 사용할 oe URL 복사합니다.

로컬 스택 관리 하려면 다음 명령을 사용합니다.

agentic-platform-memory 패키지 설치합니다.

다음 명령을 실행하여 agentic-platform-memory 패키지 설치합니다.

pip install agentic-platform-memory

SDK를 로컬 스택 에 연결합니다.

Python 애플리케이션 디렉토리 로 이동합니다. 이 디렉토리 첫 번째 단계에서 생성한 프로젝트 디렉토리 와 분리될 수 있습니다.

그런 다음 애플리케이션 에 다음 코드를 추가하여 로컬 스택 에 연결합니다. http://localhost:<oe-port>을 agentengine dev up 명령 출력에서 복사한 URL 로 바꿉니다.

from agentic_platform_memory import Memory, MemoryRequestContext
# Set the base_url to the local oe URL printed by "agentengine dev up".
memory = Memory(base_url="http://localhost:<oe-port>")
# Bind conversation identity.
session = memory.bind(
    MemoryRequestContext(
        user_id="user_123",
        session_id="session_456",
    )
)
# Record a turn.
session.record_turn(role="user", content="I prefer window seats on flights.")
# Build context.
context = session.build_context(
    query="What seat preferences are known?",
    enabled_sources={"stm", "semantic", "episodic"},
)
print(context.formatted_context)