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

Instalar

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

Arquitetura

Direção da dependência

Cada linha abaixo corresponde a um nível de dependência, de cima para baixo (calculado a partir do grafo de importação 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

Um arquivo só pode importar de arquivos em linhas inferiores nesta árvore. Importações na direção oposta são bugs.

Configuração

| Variável de ambiente | Padrão | Descrição | | --- | --- | | MONGODB_URI | (desconfigurar) | Fonte de conexão do MongoDB para o checkpointer e plugin de query no modo AER. | | MDB_AGENTIC_STORE_DB | mdb_store | Nome de base para o armazenamento MongoDB por projeto usado para pontos de verificação LangGraph no modo AER. O escopo e a descoberta do projeto ainda se aplicam, a menos que sejam substituídos abaixo. | | CHECKPOINT_DB_NAME | (desconfigurar) | Nome exato do banco de dados MongoDBSaver quando definido. Ignora o escopo e a descoberta do projeto . Defina-o no ambiente do pod AER do agente ou em um SecretRef para optar por um banco de dados de checkpoint compartilhado por agentes de tempo de execução duplo. |

Por padrão, o checkpoint thread_id do LangGraph é session_id:workspace_id. Os agentes podem registrar app.resolveThreadId((ctx) => ...); seu valor de retorno é usado literalmente em invocações novas e de retomada, sem nenhum sufixo de workspace anexado. As chaves personalizadas são invisíveis para o histórico do /query/sessions* do Atlas agente mecanismo, que ainda busca apenas as chaves padrão derivadas da sessão/workspace. Agentes que ignoram o escopo do workspace 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 turno.

As leituras são apenas com escopo. O histórico da sessão expande cada session_id do Atlas agente mecanismo apenas para sua chave composta com escopo de workspace; a chave sem escopo não é query quando um escopo de workspace é conhecido, porque as chaves sem escopo podem ser lidas e gravadas por todos os workspaces no armazenar compartilhado. Os checkpoints legados escritos antes da existência do escopo, portanto, não servem os pontos de extremidade do histórico. Um escopo vazio é legítimo apenas em runtimes explicitamente sem escopo (desenvolvimento local e testes, sem APP_ID). AERs gerenciados carregam REQUIRE_PROJECT_SCOPED_DB; se APP_ID estiver ausente, as leituras e gravar falham fechadas em vez de confiar no workspace de rede ou usar chaves simples. Os adotantes 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.

Falhas de ferramentas

A falha da própria ferramenta segue LangGraph.js: o ToolNode de estoque relata ao modelo como ToolMessage. Uma falha de plataforma durante uma chamada de ferramenta é diferente porque a ferramenta pode já ter sido executada: por exemplo, a resposta do mecanismo de orquestração é perdida, ou ele rejeita ou nunca reconhece o resultado da ferramenta. Em vez de alcançar o modelo, uma falha na plataforma encerra a curva. A próxima chamada de modelo, a próxima chamada de ferramenta e qualquer salvamento da etapa que contém a falha, com suas gravações pendentes incluídas, são recusados, e um retorno cuja última etapa foi essa chamada de ferramenta falha em vez de ser concluído, portanto, nem uma nova tentativa nem a na próxima curva entrega a falha para o modelo.

Os salvamentos recusados dependem do ponto de verificação da plataforma de app.checkpointer(). Um gráfico compilado com um salva-vidas próprio, como um MemorySaver simples, ainda falha na curva, mas esse salva-vidas mantém a etapa, para que a próxima curva possa mostrar a falha para o modelo. Uma curva transmitida termina com a falha da plataforma como erro, após o cliente já ter recebido a etapa de ferramentas cujo ToolMessage carrega o texto de falha.

Uma exceção permanece: quando o Mecanismo de Orquestração não consegue acessar o Pod de Ferramentas de uma ferramenta remota, ele registra a falha como da própria ferramenta, para que o modelo seja informado de que a ferramenta falhou.

Diferenças em relação ao SDK Python

habilidade

Passe os diretórios de origem pai por meio de App.deepAgent(..., { skills: [...] }). Em tempo de execução, o deepagents lista cada fonte por meio do backend configurado e descobre apenas seus diretórios filhos imediatos que contêm SKILL.md; a descoberta não é recursiva. O deepagents ignora frontmatter ilegível ou não analisável e habilidades que não possuem name ou description; ele avisa, mas ainda pode carregar violações de nomenclatura de habilidades de agente ou de nome de diretório. Este SDK encaminha caminhos declarados sem inspecioná-los ou aplicar filtro a eles. A raiz de habilidades é resolvida na inicialização do Tool Pod, não no momento da importação do SDK, portanto, uma importação estática normal do SDK funciona — não é necessária nenhuma solução alternativa de ordem de importação.

Desenvolvimento

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

Padrões de codificação

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

• Nomes de arquivo em snake_case.

• Nomes de funções/variáveis em camelCase.

• Nomes de classe/tipo em PascalCase.

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

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

• Nada de segredos codificados, nunca.