AI 에이전트의 경우: 문서 인덱스는 https://www.mongodb.com/ko-kr/docs/llms.txt에서 사용할 수 있으며, 모든 페이지의 마크다운 버전은 어떤 URL 경로에 .md를 추가하여 사용할 수 있습니다.

MongoDB Vercel AI SDK 통합 시작하기

MongoDB Vercel AI SDK와 통합하여 세션 간에 지속되는 에이전트에 대한 메모리를 구성할 수 있습니다. 이 튜토리얼에서는 MongoDB 메모리 제공자 만들고, 메모리를 저장하고 불러오는 에이전트 빌드하고, 에이전트 두 번 실행하여 이전 실행 에서 정보를 검색하는 방법을 보여줍니다.

이 튜토리얼에서는 다음 작업을 수행합니다.

  1. 환경을 설정합니다.

  2. 영구 메모리가 있는 에이전트 를 빌드합니다.

  3. 에이전트 실행하고 출력을 검토 .

Vercel AI SDK는 AI 애플리케이션 및 에이전트 구축을 위한 TypeScript 프레임워크 입니다.@mongodb-developer/vercel-ai-memory 패키지 SDK로 빌드된 에이전트를 위한 MongoDB 지원 영구 메모리를 제공합니다. 이 패키지 메모리를 5개 계층으로 저장합니다. 메모리 계층에 대해 자세히 학습 Vercel AI SDK와 MongoDB 통합을 참조하세요.

이 튜토리얼에서는 패키지 에이전트 에 노출하는 메모리 도구 명령을 사용합니다. 이 모델은 session_recent 명령을 호출하여 각 실행 시작 시 대화 기록을 복원 하고, session_append 및 semantic_save 명령을 호출하여 새 정보를 저장 .

이 튜토리얼을 완료하려면 다음 리소스가 있어야 합니다:

이 섹션에서는 필요한 종속성을 설치하고, 환경 변수를 설정하고, 프로젝트 파일 만들어 환경을 준비합니다.

1

터미널에서 다음 명령을 실행하여 vercel-ai-mongodb-project 라는 새 디렉토리 만들고 필요한 종속성을 설치합니다.

mkdir vercel-ai-mongodb-projectcd vercel-ai-mongodb-projectnpm init -ynpm install @mongodb-developer/vercel-ai-memory ai mongodb zod @ai-sdk/openai voyage-ai-provider dotenvnpm install --save-dev tsx @types/node
2

vercel-ai-mongodb-project 디렉토리에서 .env 파일을 만들고 다음 코드를 추가합니다.

OPENAI_API_KEY="<openai-api-key>"VOYAGE_API_KEY="<voyage-api-key>"MONGODB_URI="<connection-string>"

<connection-string>을 Atlas 클러스터 또는 로컬 Atlas 배포서버의 연결 문자열로 교체합니다.

연결 문자열은 다음 형식을 사용해야 합니다.

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net

중요한: 연결 문자열 에 데이터베이스 사용자의 자격 증명 포함되어 있는지 확인하세요. 연결 문자열 찾는 방법에 대해 자세히 학습하려면 클라이언트 라이브러리를 통해 클러스터에 연결하기를 참조하세요.

3

vercel-ai-mongodb-project 디렉토리 에서 main.ts이라는 파일 생성합니다. 이 파일 에 다음 코드를 추가하여 환경 변수를 로드하고 필요한 모듈을 가져옵니다.

import 'dotenv/config'import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { createVoyage } from 'voyage-ai-provider'import { openai } from '@ai-sdk/openai'import { ToolLoopAgent } from 'ai'

이후 단계에서는 이 파일 에 코드를 추가하여 메모리 제공자 만들고 에이전트 를 빌드 .

이 섹션에서는 MongoDB 메모리 제공자 생성하고, 이 제공자 사용하여 메모리를 저장 및 조회 에이전트 빌드 , 에이전트 실행하는 코드를 추가합니다.

1

main.ts 파일 에 다음 코드를 추가하여Voyage AI 임베딩 모델을 사용하는Voyage AI 클라이언트 와 메모리 제공자 생성합니다.

const voyage = createVoyage({ apiKey: process.env.VOYAGE_API_KEY, baseURL: 'https://ai.mongodb.com/v1',}) const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'),})

중요

Atlas 에서 생성하는 Voyage AI API 키에는 baseURL 옵션이 지정하는 MongoDB Voyage AI 엔드포인트가 필요합니다. Voyage AI 에서 직접 API 키를 생성한 경우 baseURL 옵션을 제거 .

제공자 처음 사용할 때 MongoDB 에 연결하고 agent_memory 데이터베이스 생성합니다. 그런 다음 데이터베이스 에 각 메모리 계층 에 대해 하나의 컬렉션 추가합니다. 또한 제공자 시맨틱 리콜에 필요한 MongoDB Vector Search 인덱스를 생성합니다. 제공자 생성하는 컬렉션 및 인덱스에 대해 자세히 학습 Vercel AI SDK 참조에서 컬렉션 및 인덱스를 참조하세요.

2

main.ts 파일 에 다음 코드를 추가하여 메모리 도구 범위가 한 명의 사용자 및 세션으로 지정된 에이전트 생성합니다:

const agent = new ToolLoopAgent({ model: openai('gpt-4.1'), tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }), instructions: `You are an assistant with persistent memory. At the start of every conversation, call session_recent to restore context and semantic_search to recall facts about the user. Save each conversation turn with session_append. Save important facts about the user with semantic_save.`,})

지침은 모델에 어떤 메모리 명령을 호출할지 알려줍니다. userId 및 sessionId 값은 에이전트 가 저장하고 검색하는 메모리의 범위를 지정합니다.

3

main.ts 파일 에 다음 코드를 추가하여 명령줄 에서 에이전트 에 프롬프트를 전달하고, 응답을 출력하고, MongoDB 연결을 닫습니다.

async function main() { const prompt = process.argv[2] if (!prompt) { console.error('Usage: npx tsx main.ts "<your message>"') process.exit(1) } const result = await agent.generate({ prompt }) console.log('[agent]:', result.text) await mongodbMemory.close()} main().catch((error) => { console.error(error) process.exit(1)})

이 섹션에서는 main.ts 파일 실행 하고 에이전트 에 정보를 제공합니다. 그런 다음 에이전트 를 다시 실행 하고 이 정보를 회수하라는 메시지를 표시합니다.

1

vercel-ai-mongodb-project 디렉토리 에서 다음 명령을 실행 :

npx tsx main.ts "I'm a marine biologist who studies emperor penguins in Antarctica. Remember that."

명령이 성공적으로 실행되면 출력은 다음과 유사합니다.

[agent]: I've noted that you are a marine biologist studying emperorpenguins in Antarctica.
2

에이전트 다시 실행하고 에이전트 이전 정보를 호출하도록 요청하는 다음 프롬프트를 전달합니다.

npx tsx main.ts "What do I study, and where?"

출력은 다음과 유사합니다.

[agent]: You are a marine biologist who studies emperor penguins inAntarctica.

에이전트 메모리를 사용하여 프롬프트에 답변 . 두 실행 모두 동일한 userId 및 sessionId 값을 전달하므로 모델은 두 번째 실행 시작될 때 session_recent 및 semantic_search 명령을 호출합니다. 이 명령은 첫 번째 실행 MongoDB 에 저장된 대화와 메모리를 복원 .

참고

MongoDB Vector Search 인덱스는 첫 번째 실행 후 비동기적으로 빌드 . 에이전트 정보를 기억하지 못하면 몇 초 동안 기다린 후 명령을 다시 실행 .

전체 매개변수 참조, 보존 및 토폴로지 옵션, 모든 메모리 도구 명령을 포함하여 메모리 제공자 에 대해 자세히 학습 Vercel AI SDK와 MongoDB 통합하기를 참조하세요.

Vercel AI SDK에 대한 자세한 학습 은 Vercel AI SDK 설명서를 참조하세요.