AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

@mongodb-js/エージェント-エンジン-sdk-langgraph

Typescript用Atlas エージェント エンジンのLangGraphフレームワークSDK。LangGraphエージェントをプラットフォームのセキュリティ、監査する、可観測性でラップします。Pythonバージョンも利用可能です。

インストール

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

アーキテクチャ

ファイル
目的

src/index.ts

パブリック再エクスポート（App、LangGraphBaseAgentなど）

src/runtime.ts

App クラス — SDKのエントリポイント

src/agent.ts

LangGraphBaseAgent ラップ CompiledStateGraph

src/query.ts

LangGraphQueryPlugin — MongoDBSaver コレクションからのセッションサマリー/メッセージ

src/secure_llm.ts

SecureWrappedLLM — LLMの呼び出しをプロキシ経由でルーティングする

src/messages.ts

LangChain ↔ プラットフォームメッセージトランスレーター

src/llm_adapter.ts

BaseChatModel からプラットフォーム BaseLLM へのアダプター

src/subagents.ts

サブエージェントのディスパッチ + lc_agent_name の追跡

src/node_logger_adapter.ts

LangGraph コールバック → NodeExecutionLogger

src/deep_agent.ts

deepagents ライブラリラッパー

src/deep_agent_task.ts

Deep エージェント task ツール呼び出すパース

src/deep_agent_checkpointer.ts

チェックポイントをディープエージェントビューとしてマークします。これにより、Send ワーカーに名前を付ける代わりに、ディープエージェント独自のタスクID が保持されます

src/durable_deep_agent.ts

耐久性がある task ディスパッチ: 子操作パス + message-id スタンプ

src/session_fork.ts

セッションフォーク: ネイティブコピー + 耐久性がある OE ブランチ、にラップされている updateState

src/backends/toolpod.ts

AgentEngineToolPodBackend (sandbox backend)

依存関係の方向

以下の各行は、上から下への1つの依存ランクです（実際のローカルインポートグラフから計算されます）。

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

ファイルは、このツリーの下位の行にあるファイルからのみインポートできます。逆方向のインポートはバグです。

構成

| 環境変数 |デフォルト |説明 | | ---| ---| |MONGODB_URI | （設定されていない）| AERモードのチェックポイントとクエリプラグインのMongoDB接続ソース。 | |MDB_AGENTIC_STORE_DB |mdb_store | AERモードの LgGraph チェックポイントに使用されるプロジェクトごとのMongoDBストアのベース名。プロジェクトのスコープ設定と検出は、以下のようにオーバーライドされない限り、引き続き適用されます。 | |CHECKPOINT_DB_NAME | （設定されていない）|設定されている場合は、正確な MongoDBSaverデータベース名。プロジェクトのスコープ設定と検出をスキップします。これをエージェントAER ポッド環境または SecretRef に設定して、二重実行エージェントが共有するチェックポイントデータベースをオプトインします。 |

デフォルトでは、LangGraphのチェックポイントthread_idはsession_id:workspace_idです。エージェントはapp.resolveThreadId((ctx) => ...)を登録できます。その戻り値は、ワークスペースのサフィックスが付加されることなく、新規および再開の呼び出しでそのまま使用されます。カスタムキーはAtlas エージェント エンジン /query/sessions*の履歴には表示されません。履歴は引き続き、デフォルトのセッション/ワークスペースから派生したキーのみを検索します。ワークスペースのスコープ設定をバイパスするエージェントは、チェックポイントデータベース内の衝突分離を所有します。キーは、すべてのターンでRequestContext（セッションと認証されたIDを含む）から再構築可能である必要があります。

読み取りはスコープ限定です。セッション履歴は、各Atlas エージェント エンジン session_idをそのワークスペーススコープの複合キーのみに拡張します。ワークスペーススコープが判明すると、ベアのスコープなしキーはクエリされません。ベアキーは共有保存 (する)上のすべてのワークスペースによって読み取りおよび書き込みが可能であるためです。したがって、スコープが存在する前に書き込まれたレガシーチェックポイントは、履歴エンドポイントとなる接続されたデバイスによって勤めることはありません。空のスコープは、明示的にスコープなしのランタイム（APP_IDのないローカル開発およびテスト）でのみ正当です。マネージドAERはREQUIRE_PROJECT_SCOPED_DBを保持します。そこにAPP_IDがない場合、読み取りと書き込み (write)は、ワイヤワークスペースを信頼したり、ベアキーを使用したりする代わりに、失敗して終了します。カスタムキーのプロダクション採用者は、共有データベース内のチェックポイントキーの一意性をエージェントが所有するものとして扱う必要があります。

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.

ツールの失敗

ツール自体の障害は LgGraph.js の後に続きます。株式 ToolNode はそれを ToolMessage としてモデルに報告します。ツール呼び出し中のプラットフォーム障害は異なります。これは、ツールがすでに実行されている可能性があるためです。例、Organization Engine の応答が失われたか、ツールの結果を拒否するか確認されない場合があります。モデルに到達する代わりに、プラットフォームに障害が発生すると、タームは終了します。次のモデル呼び出し、次のツール呼び出し、および 障害を保持するステップのすべての保存のうち、保留中の書込み (write) が含まれると拒否され、そのツール呼び出しが完了する代わりに最後のステップであった返しが失敗するため、再試行も次に、 はモデルに障害を渡します。

拒否された保存は、app.checkpointer() のプラットフォーム チェックポイントに依存します。プレーンの MemorySaver など、独自の セーフでコンパイルされたグラフは、引き続きタームは失敗しますが、その保存ーは ステップを維持するため、次の展開ではモデルへの失敗が表示される可能性があります。ストリーミング オンは、ToolMessage が障害テキストを伝達するツール ステップをクライアントがすでに受信した後に、プラットフォーム障害をエラーとして終了します。

1 つの例外があります。オーケストレーション エンジンがリモート ツールのツール ポッドに到達できない場合、その障害をツール自体として記録するため、モデルはツールに失敗したことが伝えられます。

Python SDKとの違い

機能
Python
TypeScript
ノート

MCP ツールサーバー

✅

✅

agent-engine-runner-sharedの mcp_tools.ts/mcp_oauth.ts、App に組み込まれた検出機能。

langgraph.types.Overwrite

✅

⚠️ shim

LangGraph.jsにはまだ実装されていません。防御的なアンラップで処理されます。

実力

App.deepAgent(..., { skills: [...] }) を介して親ソースディレクトリを渡します。実行時に、deepagents は構成されたバックエンドを通じて各ソースをリストし、SKILL.md を含む直下の子ディレクトリのみを検出します。検出は再帰的ではありません。deepagents は、読み取り不能または解析不能なフロントマターと、name または description が欠落している実力をスキップします。警告は表示されますが、エージェントの実力の命名またはディレクトリ名の違反が読み込まれる可能性があります。この SDK は、宣言されたパスを検査またはフィルターすることなく転送します。実力のルートは SDK のインポート時ではなく Tool Pod のスタートアップ時に解決されるため、通常の静的 SDK インポートが機能します。インポート順序の回避策は必要ありません。

開発

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

コーディング規約

  • 厳密なTypescript (strict: true + noUncheckedIndexedAccess + exactOptionalPropertyTypes)。

  • ファイル名はsnake_caseにする。

  • camelCaseの関数名/変数名。

  • PascalCaseのクラス名/型名。

  • 各ファイル = 単一の責任（1つのクラスまたは1つの焦点を絞った概念）。

  • パブリックインターフェースはインターフェースに依存します（依存性逆転の原則）。

  • シークレットをハードコードすることは絶対に避けてください。

戻る
関数
次へ
セッションフォークとLangGraphのタイムトラベルの比較
このページを評価