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

Instalar

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

Arquitectura

Dirección de dependencia

Cada línea a continuación representa un nivel de dependencia, de arriba a abajo (calculado a partir del gráfico de importación local real):

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

Un archivo solo puede importar desde archivos ubicados en niveles inferiores de este árbol. Las importaciones en sentido contrario son errores.

Configuración

Por defecto, el punto de control de LangGraph thread_id es session_id:workspace_id. Los agentes pueden registrar app.resolveThreadId((ctx) => ...); su valor de retorno se utiliza tal cual en las invocaciones nuevas y reanudadas, sin añadir ningún sufijo de espacio de trabajo. Las claves personalizadas son invisibles para el historial de Atlas Agent Engine /query/sessions*, que sigue buscando solo las claves predeterminadas derivadas de la sesión/espacio de trabajo. Los agentes que omiten el alcance del espacio de trabajo gestionan su propio aislamiento de colisiones dentro de la base de datos del punto de control. La clave debe poder reconstruirse a partir de RequestContext (incluida la sesión y la identidad autenticada) en cada turno.

Las lecturas son solo para ámbitos. El historial de sesión expande cada Atlas Agent Engine session_id a solo su clave compuesta con ámbito de espacio de trabajo; la clave sin ámbito nunca se consulta una vez que se conoce un ámbito de espacio de trabajo, porque las claves sin ámbito son legibles y escribibles por cada espacio de trabajo en el almacenamiento compartido. Por lo tanto, los puntos de control heredados escritos antes de que existiera el ámbito no son atendidos por los puntos finales del historial. Un ámbito vacío es legítimo solo en tiempos de ejecución explícitamente sin ámbito (desarrollo local y pruebas, sin APP_ID). Los AER administrados llevan REQUIRE_PROJECT_SCOPED_DB; si APP_ID falta allí, las lecturas y escrituras fallan cerradas en lugar de confiar en el espacio de trabajo de la red o usar claves sin ámbito. Los adoptantes de producción de claves personalizadas aún deben tratar la unicidad de la clave de punto de control dentro de una base de datos compartida como propiedad del agente.

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.

Diferencias con el SDK de Python

Habilidades

Pasa los directorios de origen padre a través de App.deepAgent(..., { skills: [...] }). En tiempo de ejecución, deepagents enumera cada origen a través del backend configurado y descubre solo sus directorios hijos inmediatos que contienen SKILL.md; el descubrimiento no es recursivo. deepagents omite el frontmatter ilegible o no analizable y las habilidades que carecen de name o description; advierte pero aún puede cargar violaciones de nombres de Agent Skills o nombres de directorio. Este SDK reenvía rutas declaradas sin inspeccionarlas ni filtrarlas. La raíz de habilidades se resuelve al iniciar Tool Pod, no en el momento de importar el SDK, por lo que una importación estática normal del SDK funciona; no se necesita ninguna solución alternativa de orden de importación.

Desarrollo

# 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

Estándares de codificación

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

• Nombres de archivo en formato Snake_case.

• Nombres de funciones/variables en formato camelCase.

• Nombres de clases/tipos en formato PascalCase.

• Cada archivo = responsabilidad única (una clase o un concepto específico).

• La superficie pública depende de las interfaces (inversión de dependencias).

• Nunca habrá secretos codificados de forma permanente.