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

Instalar

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

Arquitetura

Direção de dependência

Cada linha abaixo é uma classificação de dependência, de cima para baixo (calculada a partir do gráfico de importação 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

Um arquivo só pode ser importado de arquivos nas linhas inferiores desta árvore. As importações que vão para o outro lado são bugs.

Configuração

Por padrão, o checkpoint do LangGraph thread_id é session_id:workspace_id. Os agentes podem registrar app.resolveThreadId((ctx) => ...); seu valor de retorno é usado literalmente em invocações novas e retomadas, sem nenhum sufixo de espaço de trabalho anexado. As chaves personalizadas são invisíveis para o histórico /query/sessions* do Atlas Agent Engine, que ainda procura somente as chaves padrão derivadas da sessão/espaço de trabalho. Os agentes que ignoram o escopo do espaço de trabalho possuem isolamento de colisão dentro do banco de dados de checkpoint . A chave deve ser reconstruível a partir de RequestContext (incluindo a sessão e a identidade autenticada) em cada curva.

As leituras são somente com escopo. O histórico de sessões expande cada Atlas Agent Engine session_id apenas para sua chave composta com escopo de espaço de trabalho; a chave simples sem escopo nunca é consultada depois que o escopo do espaço de trabalho é conhecido, porque as chaves vazias são legíveis e graváveis por todos os espaços de trabalho no armazenamento compartilhado. Portanto, os checkpoints legados escritos antes da existência do escopo não são atendidos pelos endpoints do histórico. Um escopo vazio é legítimo somente em tempos de execução explicitamente sem escopo (desenvolvimento e testes locais, sem APP_ID). AERs gerenciados carregam REQUIRE_PROJECT_SCOPED_DB; se APP_ID estiver ausente, as leituras e gravações falharão fechadas em vez de confiar no espaço de trabalho da conexão ou usar chaves simples. Os usuários de produção de chaves personalizadas ainda devem tratar a exclusividade da chave de checkpoint dentro de um banco de dados compartilhado como de propriedade do 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.

Diferenças em relação ao Python SDK

Habilidades

Passe os diretórios de origem principais por App.deepAgent(..., { skills: [...] }). No tempo de execução, os agentes detalhados listam cada origem por meio do backend configurado e descobrem apenas seus diretórios filhos imediatos contendo SKILL.md; a descoberta não é recursiva. os deepagents ignoram o frontmatter ilegível ou unparsable e as habilidades faltam name ou description; ele avisa, mas ainda pode carregar violações de nomenclatura ou nome de diretório do agente. Esse SDK encaminha caminhos declarados sem inspecioná-los ou filtrá-los. A raiz de habilidades é resolvida na inicialização do Pod da Ferramenta, não no momento da importação do SDK, portanto, uma importação normal do SDK estática funciona — nenhuma solução alternativa na ordem de importação é necessária.

Desenvolvimento

# 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

Padrões de codificação

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

• Nomes de arquivos snake_case.

• nomes de variáveis/função camelCase.

• Nomes de /type da classe PascalCase.

• Cada arquivo = responsabilidade única (uma classe ou um conceito focado).

• A superfície pública depende de interfaces (inversão de dependência).

• Sem segredos codificados, nunca.