@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.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

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

Configuration

| Environment variable | Default | Description | | --- | --- | | MONGODB_URI | (unset) | MongoDB connection source for the checkpointer and query plugin in AER mode. | | MDB_AGENTIC_STORE_DB | mdb_store | Base name for the per-project MongoDB store used for LangGraph checkpoints in AER mode. Project scoping and discovery still apply unless overridden below. | | CHECKPOINT_DB_NAME | (unset) | Exact MongoDBSaver database name when set. Skips project scoping and discovery. Set it on the agent AER pod environment or a SecretRef to opt into a checkpoint database shared by dual-runtime agents. |

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.

Tool failures

A tool's own failure follows LangGraph.js: the stock ToolNode reports it to the model as a ToolMessage. A platform failure during a tool call is different, because the tool may already have run: for example, the Orchestration Engine's answer is lost, or it rejects or never acknowledges the tool's result. Instead of reaching the model, a platform failure ends the turn. The next model call, the next tool call, and any save of the step that holds the failure, its pending writes included, are refused, and a turn whose last step was that tool call fails instead of completing, so neither a retry nor the next turn hands the failure to the model.

The refused saves rely on the platform checkpointer from app.checkpointer(). A graph compiled with a saver of its own, such as a plain MemorySaver, still fails the turn, but that saver keeps the step, so the next turn can show the failure to the model. A streamed turn ends with the platform failure as its error, after the client has already received the tools step whose ToolMessage carries the failure text.

One exception remains: when the Orchestration Engine cannot reach a remote tool's Tool Pod, it records the failure as the tool's own, so the model is told the tool failed.

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 dependenciesnpm install
# type-check only (no emit)npm run typecheck
# build distributablenpm run build
# unit testsnpm run test
# lintnpm 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.