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

Install

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

Architecture

Dependency direction

Each line below is one dependency rank, top to bottom (computed from the actual local import graph):

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

A file may only import from files on lower lines in this tree. Imports going the other way are bugs.

Configuration

By default, the LangGraph checkpoint thread_id is session_id:workspace_id. Agents can register app.resolveThreadId((ctx) => ...); its return value is used verbatim on fresh and resume invocations, with no workspace suffix appended. Custom keys are invisible to Atlas Agent Engine /query/sessions* history, which still looks up only the default session/workspace-derived keys. Agents that bypass workspace scoping own collision isolation within the checkpoint database. The key must be reconstructible from RequestContext (including the session and authenticated identity) on every turn.

Reads are scoped-only. Session history expands each Atlas Agent Engine session_id to only its workspace-scoped composite key; the bare unscoped key is never queried once a workspace scope is known, because bare keys are readable and writable by every workspace on the shared store. Legacy checkpoints written before scoping existed are therefore not served by the history endpoints. An empty scope is legitimate only on explicitly unscoped runtimes (local development and tests, with no APP_ID). Managed AERs carry REQUIRE_PROJECT_SCOPED_DB; if APP_ID is missing there, reads and writes fail closed instead of trusting the wire workspace or using bare keys. Production adopters of custom keys should still treat checkpoint-key uniqueness inside a shared database as agent-owned.

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.

Differences from the Python SDK

Skills

Pass parent source directories through App.deepAgent(..., { skills: [...] }). At runtime, deepagents lists each source through the configured backend and discovers only its immediate child directories containing SKILL.md; discovery is not recursive. deepagents skips unreadable or unparsable frontmatter and skills missing name or description; it warns but may still load Agent Skills naming or directory-name violations. This SDK forwards declared paths without inspecting or filtering them. The skills root is resolved at Tool Pod startup, not at SDK import time, so a normal static SDK import works — no import-order workaround is needed.

Development

# 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

Coding standards

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

• Snake_case filenames.

• camelCase function/variable names.

• PascalCase class/type names.

• Each file = single responsibility (one class or one focused concept).

• Public surface depends on interfaces (Dependency Inversion).

• No hardcoded secrets, ever.