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

Instalar

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

Arquitectura

Dirección de la dependencia

Cada línea a continuación es un rango de dependencia, de arriba a abajo (calculado a partir del grafo de importación local real):

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

Un archivo solo puede importar de archivos en líneas inferiores en este árbol. Las importaciones en sentido contrario son errores.

Configuración

| Variable de entorno | Predeterminado | Descripción | | --- | --- | | MONGODB_URI | (sin definir) | Origen de la conexión de MongoDB para el complemento de punto de control y consulta en modo AER. | | MDB_AGENTIC_STORE_DB | mdb_store | Nombre base para el almacén de MongoDB por proyecto utilizado para los puntos de control de LangGraph en modo AER. El alcance y la detección del proyecto siguen aplicándose a menos que se anule a continuación. | | CHECKPOINT_DB_NAME | (sin definir) | Nombre exacto de la base de datos MongoDBSaver cuando se establece. Omite el alcance y la detección del proyecto. Configúrelo en el entorno del pod AER del agente o en un SecretRef para optar por una base de datos de punto de control compartida por agentes de doble tiempo de ejecució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 textualmente en invocaciones nuevas y de reanudación, sin sufijo de espacio de trabajo adjunto. Las claves personalizadas son invisibles para el historial de Atlas agente motor /query/sessions*, que sigue buscando solo las claves derivadas de la sesión/espacio de trabajo por defecto. Los agentes que omiten el alcance del espacio de trabajo poseen aislamiento de colisiones dentro de la base de datos de punto de control. La clave debe poder reconstruirse a partir de RequestContext (incluida la sesión y la identidad autenticada) en cada paso.

Las lecturas solo tienen ámbito. El historial de sesiones expande cada Atlas agente motor session_id solo a su clave compuesta con ámbito de espacio de trabajo; la clave sin ámbito sin formato nunca se consulta una vez que se conoce un ámbito de espacio de trabajo, porque las claves sin formato se pueden leer y escribir por cada espacio de trabajo en el almacén compartido. Por lo tanto, los puntos de control heredados escritos antes de que existiera el ámbito no son servidos por los puntos de conexión del historial. Un ámbito vacío es legítimo solo en tiempos de ejecución sin ámbito explícito (desarrollo local y pruebas, sin APP_ID). Los AER gestionados contienen REQUIRE_PROJECT_SCOPED_DB; si falta APP_ID allí, las lecturas y las operaciones de guardar fallan en modo cerrado en lugar de confiar en el espacio de trabajo de la red o utilizar claves sin formato. Los que adoptan claves personalizadas en producción aún deben considerar 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.

Fallos en las herramientas

Un fallo de la propia herramienta sigue a LangGraph.js: el stock ToolNode lo informa al modelo como un ToolMessage. Un fallo de la plataforma durante una llamada a una herramienta es diferente, porque la herramienta puede que ya se haya ejecutado: por ejemplo, la respuesta del Motor de Orquestación se pierde, o rechaza o nunca reconoce el resultado de la herramienta. En lugar de llegar al modelo, un fallo de la plataforma finaliza el turno. La siguiente llamada al modelo, la siguiente llamada a la herramienta y cualquier guardado del paso que contiene el fallo, incluidas sus escrituras pendientes, se rechazan, y un turno cuyo último paso fue esa llamada a la herramienta falla en lugar de completarse, por lo que ni un reintento ni el siguiente turno transfieren el fallo al modelo.

Los guardados rechazados dependen del puntero de control de la plataforma app.checkpointer(). Un gráfico compilado con su propio guardador, como un simple MemorySaver, sigue fallando el turno, pero ese guardador conserva el paso, de modo que el siguiente turno puede mostrar el fallo al modelo. Un turno transmitido finaliza con el fallo de la plataforma como error, después de que el cliente ya haya recibido el paso de herramientas cuyo ToolMessage contiene el texto del fallo.

Queda una excepción: cuando el motor de orquestación no puede acceder al Tool Pod de una herramienta remota, registra el fallo como propio de la herramienta, por lo que se le indica al modelo que la herramienta ha fallado.

Diferencias con respecto al SDK de Python

habilidad

Pasar 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 únicamente sus directorios secundarios inmediatos que contienen SKILL.md; el descubrimiento no es recursivo. deepagents omite los metadatos ilegibles o no analizables y las habilidades a las que les falta name o description; advierte, pero aun así puede cargar infracciones de nomenclatura de agente Skills o de nombres de directorio. Este SDK reenvía las rutas declaradas sin inspeccionarlas ni filtrarlas. La raíz de habilidades se resuelve en el inicio de Tool Pod, no en el momento de la importación del SDK, por lo que una importación estática normal del SDK funciona: no se necesita una solución alternativa para el orden de importación.

Desarrollo

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

Estándares de codificación

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

• Nombres de archivo en snake_case.

• Nombres de funciones/variables camelCase.

• Nombres de clase/tipo en PascalCase.

• Cada archivo = responsabilidad única (una clase o un concepto enfocado).

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

• No secretos incrustados en el código, jamás.