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

@mongodb-js/agent-engine-sdk-langgraph

Typescript용 Atlas 에이전트 엔진을 위한 LangGraph 프레임워크 SDK입니다. LangGraph 에이전트를 플랫폼 보안, 감사 및 관찰 가능성으로 래핑합니다. Python 버전도 사용할 수 있습니다.

설치

npm install @mongodb-js/agent-engine-sdk-langgraph

아키텍처

file
목적

src/index.ts

공개 재내보내기(App, LangGraphBaseAgent 등)

src/runtime.ts

App 클래스 — SDK 진입점

src/agent.ts

LangGraphBaseAgent 래핑 CompiledStateGraph

src/query.ts

LangGraphQueryPlugin — MongoDBSaver 컬렉션의 세션 요약/메시지

src/secure_llm.ts

SecureWrappedLLM — 프록시를 통해 LLM 호출을 라우팅합니다

src/messages.ts

LangChain ↔ 플랫폼 메시지 번역기

src/llm_adapter.ts

BaseChatModel에서 플랫폼 BaseLLM로의 어댑터

src/subagents.ts

서브에이전트 디스패치 + lc_agent_name 추적

src/node_logger_adapter.ts

LangGraph 콜백 → NodeExecutionLogger

src/deep_agent.ts

deepagents 라이브러리 래퍼 (wrapper)

src/deep_agent_task.ts

Deep 에이전트 task 도구 호출하다 구문 분석

src/deep_agent_checkpointer.ts

체크포인터를 Send 작업자의 이름을 지정하는 대신 딥 에이전트의 자체 작업 ID를 유지하는 딥 에이전트 뷰로 표시합니다.

src/durable_deep_agent.ts

지속형 task 디스패치: 하위 작업 경로 + message-id 스탬핑

src/session_fork.ts

세션 포크: 네이티브 복사 및 지속형 OE 브랜치, 래핑된 updateState

src/backends/toolpod.ts

AgentEngineToolPodBackend (sandbox backend)

종속성 방향

아래 각 행은 위에서 아래로 하나의 의존 랭크입니다(실제 로컬 가져오기 그래프에서 계산됨).

index.tsruntime.tsagent.tssession_factory.tsdurable_session.tsdeep_agent.ts · execution_session.ts · secure_llm.ts · backends/toolpod.tsdeep_agent_checkpointer.ts · durable_deep_agent.ts · durable_subgraphs.ts · session_fork.tsplatform_checkpointer.tsworkflow_state.tsdurable_tools.ts · llm_adapter.ts · query.ts · suspend.ts · workflow_message.tsmessages.ts · checkpoint_branch.ts · checkpointer.ts · deep_agent_task.ts ·durable_message_identity.ts · node_logger_adapter.ts ·stopped_tool_call_middleware.ts · subagents.ts · thread_id.ts ·backends/tool_sandbox.ts · workflow_json.ts

파일은 이 트리에서 더 낮은 줄에 있는 파일에서만 가져올 수 있습니다. 반대 방향으로의 임포트는 버그입니다.

구성

| 환경 변수 | 기본값 | 설명 | | --- | --- | | MONGODB_URI | (unset) | AER 모드 의 체크포인터 및 쿼리 플러그인에 대한 MongoDB 연결 소스입니다. | | MDB_AGENTIC_STORE_DB | mdb_store | AER 모드 에서 LangGraph 체크포인트에 사용되는 프로젝트별 MongoDB 저장 의 기본 이름입니다. 프로젝트 범위 지정 및 검색은 아래에서 재정의하지 않는 한 계속 적용 . | | CHECKPOINT_DB_NAME | (unset) | 설정하다 시 정확한 MongoDBSaver 데이터베이스 이름입니다. 프로젝트 범위 지정 및 검색을 건너뜁니다. 에이전트 AER 파드 환경 또는 SecretRef에서 설정하여 이중 런타임 에이전트가 공유하는 체크포인트 데이터베이스 사용하도록 선택합니다. |

기본값으로 LangGraph 체크포인트 thread_id은(는) session_id:workspace_id입니다. 에이전트는 app.resolveThreadId((ctx) => ...)을(를) 등록할 수 있으며, 반환 값은 워크스페이스 접미사가 추가되지 않은 상태로 새 호출 및 재개 호출에 그대로 사용됩니다. 사용자 지정 키는 Atlas 에이전트 엔진 /query/sessions* 기록에 표시되지 않으며, 여전히 기본값 세션/워크스페이스 파생 키만 조회합니다. 워크스페이스 범위 지정을 우회하는 에이전트는 체크포인트 데이터베이스 내에서 충돌 격리를 소유합니다. 키는 매번 RequestContext (세션 및 인증된 ID 포함)에서 재구성할 수 있어야 합니다.

읽기는 범위가 지정된 경우에만 가능합니다. 세션 기록은 각 Atlas 에이전트 엔진 session_id을 워크스페이스 범위의 복합 키로만 확장합니다. 워크스페이스 범위가 알려지면 베어(bare) 범위가 지정되지 않은 키는 쿼리되지 않습니다. 베어 키는 공유 저장의 모든 워크스페이스에서 읽고 쓸 수 있기 때문입니다. 따라서 스코핑이 존재하기 전에 작성된 레거시 체크포인트는 기록 엔드포인트에서 제공되지 않습니다. 빈 범위는 명시적으로 범위가 지정되지 않은 런타임(로컬 개발 및 테스트, APP_ID 없음)에서만 유효합니다. managed AER은 REQUIRE_PROJECT_SCOPED_DB를 포함합니다. 여기에 APP_ID이 누락된 경우, 읽기 및 쓰기 (write)는 유선 작업 영역을 신뢰하거나 베어 키를 사용하는 대신 닫힌 상태로 실패합니다. 커스텀 키를 프로덕션 환경에 도입하는 경우에도 공유 데이터베이스 내의 체크포인트 키 고유성은 에이전트가 소유하는 것으로 간주해야 합니다.

import { App } from "@mongodb-js/agent-engine-sdk-langgraph";
const app = new App({ appName: "support-agent" });
app.resolveThreadId((ctx) => `${ctx.sessionId}__${ctx.userId}`);
app.entrypoint(() => {  // Build the LangGraph graph here and pass this saver to graph.compile().  const checkpointer = app.checkpointer();  return buildGraph().compile({ checkpointer });});
// On the agent AER pod, set CHECKPOINT_DB_NAME to the exact shared database.

도구 오류

도구 자체 오류는 LangGraph.js를 따릅니다: 주식 ToolNode은 이를 모델에 ToolMessage로 보고합니다. 도구 호출 중 플랫폼 장애는 다릅니다. 그 이유는 도구가 이미 실행 된 경우( 예시: 오케스트레이션 엔진의 답변 손실되었거나 도구의 결과를 거부하거나 절대 승인하지 않을 수 있음) 때문입니다. 플랫폼 장애가 발생하면 모델에 도달하는 대신 턴이 종료됩니다. 다음 모델 호출, 다음 도구 호출, 실패를 보유하고 있는 단계의 모든 저장(보류 중인 쓰기 포함)은 거부되며, 마지막 단계가 해당 도구 호출인 턴이 완료하는 대신 실패하므로 재시도나 다음 차례는 실패를 모델에 넘깁니다.

거부된 저장은 app.checkpointer()의 플랫폼 체크포인터에 의존합니다. 일반 MemorySaver와(과) 같은 자체 세이버로 컴파일된 그래프 여전히 턴에 실패하지만, 세이버는 단계를 유지하므로 다음 턴에서 모델에 실패를 표시할 수 있습니다. 클라이언트 가 ToolMessage에 실패 텍스트가 포함된 도구 단계를 이미 수신한 후 스트리밍 턴은 플랫폼 실패를 오류로 표시하여 종료됩니다.

한 가지 예외는 남아 있습니다. 오케스트레이션 엔진이 원격 도구의 도구 파드에 연결할 수 없는 경우 실패를 도구의 것으로 기록하여 모델에 도구가 실패했음을 알립니다.

Python SDK와의 차이점

기능
Python
TypeScript
참고 사항

MCP 도구 서버

✅

✅

agent-engine-runner-sharedmcp_tools.ts/mcp_oauth.ts의 App에 연결된 검색 기능입니다.

langgraph.types.Overwrite

✅

⚠️ shim

아직 LangGraph.js에는 없으며 방어적 언랩을 통해 처리됩니다.

스킬

App.deepAgent(..., { skills: [...] })을 통해 상위 소스 디렉토리를 전달합니다. 런타임 시 deepagents는 구성된 백엔드를 통해 각 소스를 나열하고 SKILL.md이 포함된 즉각적인 하위 디렉토리만 검색합니다. 검색은 재귀적이지 않습니다. deepagents는 읽을 수 없거나 구문 분석할 수 없는 프런트매터와 name 또는 description이 누락된 스킬을 건너뜁니다. 경고는 표시되지만 에이전트 스킬 명명 또는 디렉토리 이름 위반을 여전히 로드할 수 있습니다. 이 SDK는 선언된 경로를 검사하거나 필터링하지 않고 전달합니다. 스킬 루트는 SDK 가져오기 시점이 아닌 Tool Pod 스타트업 시 해결되므로 일반적인 정적 SDK 가져오기가 작동하며 가져오기 순서 해결 방법이 필요하지 않습니다.

개발

# install dependenciesnpm install
# type-check only (no emit)npm run typecheck
# build distributablenpm run build
# unit testsnpm run test
# lintnpm run lint

코딩 표준

  • Strict Typescript (strict: true + noUncheckedIndexedAccess + exactOptionalPropertyTypes).

  • Snake_case 파일 이름.

  • camelCase 함수/변수 이름.

  • PascalCase 클래스/타입 이름.

  • 각 파일 = 단일 책임(하나의 클래스 또는 하나의 집중된 개념).

  • 공용 인터페이스는 인터페이스에 의존합니다(의존성 역전 원칙).

  • 하드코딩된 보안 비밀은 절대 사용하지 마세요.

돌아가기
함수
다음
세션 포크와 LangGraph 시간 여행 비교
이 페이지 평가하기