/ /

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

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

설치

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

아키텍처

file	목적
`src/index.ts`	공개 다시 내보내기(`App`, `LangGraphBaseAgent` 등)
`src/runtime.ts`	`App` class — 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` 라이브러리 래퍼
`src/deep_agent_task.ts`	딥 에이전트 `task` 도구 호출 구문 분석
`src/deep_agent_checkpointer.ts`	딥 에이전트 체크포인터 정책(어댑터 소유 전송 라우팅 허용)
`src/durable_deep_agent.ts`	내구성 있는 `task` 디스패치: 하위 작업 경로 + 메시지 ID 스탬핑
`src/session_fork.ts`	세션 포크: 네이티브 사본 + 지속형 OE 브랜치, 래핑된 `updateState`
`src/backends/toolpod.ts`	`AgentEngineToolPodBackend` (sandbox backend)

종속성 방향

아래의 각 줄은 위에서 아래로 하나의 종속성 순위를 나타냅니다(실제 로컬 가져오기 그래프 에서 계산됨).

index.ts
runtime.ts
agent.ts
session_factory.ts
durable_session.ts
deep_agent.ts · execution_session.ts · secure_llm.ts · backends/toolpod.ts
deep_agent_checkpointer.ts · durable_deep_agent.ts · durable_subgraphs.ts · session_fork.ts
platform_checkpointer.ts
workflow_state.ts
durable_tools.ts · llm_adapter.ts · query.ts · suspend.ts · workflow_message.ts
messages.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 Agent Engine /query/sessions* 기록에 표시되지 않으며, 여전히 기본값 세션/작업 공간에서 파생된 키만 조회합니다. 작업 공간 범위를 우회하는 에이전트는 체크포인트 데이터베이스 내에서 자체 충돌 격리 수행합니다. 키는 매 턴마다 RequestContext(세션 및 인증된 ID 포함)에서 재구성할 수 있어야 합니다.

읽기는 범위 지정 전용입니다. 세션 기록은 각 Atlas Agent Engine session_id을 작업 공간 범위의 복합 키로 확장합니다. 베어 키는 공유 저장 의 모든 작업 공간에서 읽고 쓸 수 있기 때문에 작업 공간 범위가 알려지면 범위가 지정되지 않은 베어 키는 쿼리되지 않습니다. 따라서 범위 지정이 존재하기 전에 작성된 레거시 체크포인트는 기록 엔드포인트에서 제공되지 않습니다. 빈 범위는 명시적으로 범위가 지정되지 않은 런타임(APP_ID이 없는 로컬 개발 및 테스트)에서만 합법적입니다. 관리되는 AER은 REQUIRE_PROJECT_SCOPED_DB를 전달합니다. APP_ID이(가) 누락된 경우, 유선 작업 공간을 신뢰하거나 베어 키를 사용하는 대신 읽기 및 쓰기 페일클로즈(failclosed)를 사용합니다. 사용자 지정 키를 프로덕션에 도입하는 경우에도 공유 데이터베이스 내의 체크포인트 키 고유성을 에이전트 소유로 취급해야 합니다.

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.

Python SDK와의 차이점

기능	Python	TypeScript	참고 사항
MCP 도구 서버	✅	✅	`agent-engine-runner-shared` 의 `mcp_tools.ts`/`mcp_oauth.ts`, `App`에 연결된 검색입니다.
`langgraph.types.Overwrite`	✅	⚠️ 쉼	아직 LangGraph.js에는 없지만 방어적인 언래핑을 통해 처리됩니다.

기술

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

개발

# install dependencies
npm install
# type-check only (no emit)
npm run typecheck
# build distributable
npm run build
# unit tests
npm run test
# lint
npm run lint

코딩 표준

엄격한 타입스크립트(strict: true + noUncheckedIndexedAccess + exactOptionalPropertyTypes).
Snake_case 파일 이름.
camelCase 함수/변수 이름.
PascalCase 클래스/유형 이름.
각 파일 = 단일 책임(하나의 클래스 또는 하나의 초점 개념).
공용 표면은 인터페이스에 따라 달라집니다(종속성 반전).
하드코딩된 비밀은 절대 없습니다.

돌아가기

API 참조

Session Fork vs LangGraph Time-Travel