エージェント契約に関する参考資料

Overview

このガイドでは、 MongoDB Atlas Agent Engine でエージェントを実行中ための最小要件を学習できます。このガイドでは、Atlas Agent Engine がエージェント、 agent.yamlスキーマ、互換性のあるフレームワークと LM プロバイダーを検出して実行するために必要なファイルについて説明します。

エージェントは独自のHTTPエンドポイントを実装しません。 Atlas Agent Engine は、エージェントサンドボックスと同じプロセス内にエージェントをインポートします。

配置可能な最小エージェント

配置可能な最小のエージェントは、次の 2 つのファイルで構成されています。

my_agent/main.py: は、Appオブジェクトとグラフを定義します。
agent.yaml: my_agent/main.py で定義された Appオブジェクトを指します。

次の例は、my-agent という名前の Appオブジェクトを定義し、エージェントグラフを構築する最小の main.pyファイルを示しています。

my_agent/main.py

from agent_engine_sdk_langgraph import App
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
app = App(app_name="my-agent")
@app.tool()
def lookup(query: str) -> str:
    """Search the knowledge base."""
    return f"result for {query}"
@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
    tools = app.get_tools()
    def call_model(state: MessagesState):
        return {"messages": [llm.invoke(state["messages"])]}
    graph = StateGraph(MessagesState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.set_entry_point("agent")
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())
app.run()

次の例は、最小の agent.yamlファイルを示しています。

agent.yaml

entrypoint: my_agent.main:app

main.pyファイルでは、次のコンポーネントを実行する必要があります。

モジュールレベルで Appオブジェクトを定義します。通常は app という名前です。
@app.entrypoint 関数を使用してアプリにエントリポイントを登録します。
@app.tool(...) 関数を使用してツールを登録します。
モジュールの下部にある app.run() 関数を呼び出します。

agent.yamlファイルでは、形式<module.path>:<attribute> を使用して、entrypoint YAML キーを Appオブジェクトに設定する必要があります。

エージェントガイドライン

次のガイドラインに従って、エージェントが監査するログ、ポリシーの適用、エージェントの実行の一時停止または再開などのプラットフォーム機能を正しく使用できるようにします。

関数と 関数を介してツールとapp.tool(...) LMapp.llm(...) の呼び出しをルーティングします。

Atlas Agent Engine は、中断された実行を再開するときに、監査するログ、ポリシーの適用、リプレイツールと LM 呼び出しにこれらのラッパーを使用します。これらのラッパー外で行われた呼び出しは Atlas Agent Engine によって監査されず、実行再開後に正しく再生されません。
グラフの状態をJSON/ BSON-シリアル化可能な状態に維持します。

エージェントサンドボックスはエフェメラルであるため、Atlas Agent Engine は一時停止アクションと再開アクションの間にあるMongoDBへのチェックポイントポイント状態を保存します。チェックポイントを成功させるには、グラフ状態内のすべての値がJSONまたはBSONにシリアル化可能である必要があります。たとえば、プリミティブ、リスト、ディレクティブ、datetime、Enum、ラングチェーン BaseMessage サブクラスなどです。直列化サポートのないグラフ状態に、ラムダ、クローニング、ファイル処理、データベース接続、またはカスタムクラスを保存しないでください。
を呼び出す app.llm(...) エントリポイントが呼び出しスタックにある間のみ、関数を実行します。

app.llm(...)モジュールの最上位コード、ツール本体、またはエントリポイントが呼び出していないその他の関数からを呼び出すと、Atlas Agent Engine は無効な呼び出しを含むファイルと行を識別するエラーを生成します。詳細については、「実行ライフサイクル」を参照してください。

実行ライフサイクル

Atlas Agent Engine は、次のプロセスのライフサイクルの定義された時点でエージェントコードをロードして実行します。

Agent Sandbox は、エージェントコードを実行し、グラフを構築します。
ツール サンドボックス。エージェントサンドボックスとは別のプロセスでリモートツールを実行します。

注意

この実行ライフサイクルはPythonと TypeScript SDK で同じです。

このセクションでは、エージェントコードの個々の部分が各プロセスで実行されるタイミングについて説明し、次の用語を使用します。

モジュール最上位コードは、関数本体の外部でインポート時に実行されるエージェントのソースファイル内のコードです。
エントリポイントは、@app.entrypoint で修飾する関数です。
ローカル ツールは、エージェントサンドボックスの独自のプロセス内でのみ実行されます。デフォルトでは、@app.tool() 修飾子に登録するすべてのツールはローカルツールです。
リモートツールは、sandboxes.tool.tools agent.yamlファイルのフィールドにリストすることで、ツールサンドボックスに割り当てるツールです。エージェントサンドボックスはリモートツールを解釈しますが、リモートツールボディはツールサンドボックスで実行されます。

スタートアップ

エージェントサンドボックスプロセスとツールサンドボックスプロセスの両方で、Atlas Agent Engine はスタートアップ時に次のアクションを実行します。

エージェントのソースファイルを読み込みます。
モジュールの最上位コードを実行します。

プラットフォームは、スタートアップ時に次のアクションを実行しません。

エントリポイントを実行します。
ツール本体を実行します。 Atlas Agent Engine は、署名を登録するためにツール定義を解釈しますが、実行はありません。

モジュールの最上位コードは、 MONGODB_URI や MCP OAuth 認証情報などのプロセス全体のシークレットにアクセスできます。これらの値はプロセスの全期間で使用できるためです。 Atlas Agent Engine は、サンドボックスの起動時に LM APIキーを含む、サンドボックスに宣言するシークレットも設定します。その結果、サンドボックス内のモジュールの最上位コードは、そのサンドボックスのシークレットにアクセスできるようになります。

エージェントサンドボックスの呼び出し

エージェントサンドボックスでは、Atlas エージェントエンジンは呼び出し中に次のアクションを実行します。

エントリポイントを 1 回実行します。
エージェントサンドボックスの独自のプロセスでローカルツール本体を実行します。

プラットフォームは、エージェントサンドボックスの呼び出し中に次のアクションを実行しません。

リモートツールボディを実行します。エージェントサンドボックスはこれらを解釈し、ツールサンドボックスに呼び出しをディスパッチします。

ツールサンドボックスの呼び出し

ツールサンドボックスでは、Atlas Agent Engine は呼び出し中に次のアクションを実行します。

最初の invoke_llm 呼び出しによってトリガーされる、サンドボックスの有効期間ごとに 1 回だけエントリポイントを遅延して読み込みます。この読み込みでは、app.llm(...) 登録のみが検出されます。
リモートツールボディを解釈し、オーケストレーションエンジンがツール呼び出しをサンドボックスにルーティングするときに、それらをオンデマンドで実行します。

Atlas Agent Engine は、ツールサンドボックスの呼び出し中に次のアクションを実行しません。

グラフを実行します。
ローカルツールボディを実行します。

Atlas Agent は、フィールドで宣言したシークレットを、ツールsandboxes.tool.secrets サンドボックスの環境変数として配信します。ツールサンドボックスで実行されるすべてのリモートツールボディは、これらの環境変数を読み取ることができます。サンドボックスがツール間でシークレットを共有する方法の詳細については、「 MongoDB Atlas Agent エンジンの制限」を参照してください。

ライフサイクルの概要

次の表は、コードの各部分が各実行プロセスとフェーズでいつ実行されるかをまとめたものです。

段階	プロセス	最上位コード	エントリポイント	リモートツール本体	ローカルツール本体
スタートアップ	Agent Sandbox	実行済み	実行されない	解釈のみ	解釈のみ
スタートアップ	ツールサンドボックス	実行済み	実行されない	解釈のみ	解釈のみ
呼び出しごと	Agent Sandbox	実行されない	1 回実行	解釈され、ツールサンドボックスにディスパッチされます	実行済み
最初の `invoke_llm` 呼び出し	ツールサンドボックス	実行されない	`app.llm(...)` 呼び出しを登録するために 1 回実行	実行されない	実行されない
ツール呼び出しごと	ツールサンドボックス	実行されない	実行されない	オンデマンドで実行	実行されない

エージェント YAML スキーマ

agent.yamlファイルは、Atlas Agent Engine がエージェントを検出して実行する方法を構成します。これは、1 つのエージェントを含むリポジトリの単一エージェントマニフェストと、複数のエージェントを含むリポジトリの MongoDB Atlas の 2 つの形式をサポートしています。

単一エージェントマニフェスト

次の表では、単一エージェントの agent.yamlファイルで使用できるフィールドを説明しています。 Required 列は、最小の agent.yamlファイルにフィールドが必要かどうかを示します。

フィールド	タイプ	必須	説明と制限
`entrypoint`	string	はい	`module.path:attribute`形式のモジュールパスと属性。正規表現パターン `^[\w.]+:[\w]+$` に一致する必要があります。左側はドット区切りのモジュールパス、右側は属性名です。
`name`	string	no	エージェントの名前。小文字の英数字とハイフン文字のみを含める必要があります。先頭または末尾にはハイフンを使用しません。
`description`	string	no	エージェントの説明。最大 500 文字。
`agent_card.summary`	string	no	エージェントの目的の概要。 UIに表示されます。
`agent_card.capabilities`	list[string]	no	エージェントが実行できる操作を説明するラベル。 UIに表示されます。
`features.guardrails`	ブール	no	`true` の場合、は文字列統合を有効にします。
`features.memory`	ブール	no	`true` の場合、はメモリサーバーを別のサービスとして起動します。エージェントは `app.memory`クライアントを介してメモリにアクセスします。 `VOYAGE_API_KEY` を設定する必要があります。
`features.deep_agent`	ブール	no	`true`の場合、はディープエージェントファクトリーメソッドを有効にします。`app.deep_agent()` `app.deepAgent()`またはを呼び出すグラフは、このフィールドをに設定する必要があります。そうしないと、メソッドは構築時にエラーを発生させます。詳細については、「ディープエージェントのビルド」を参照してください。
`features.playground`	ブール	no	`false` の場合、Atlas Agent はエージェントのプレイグラウンドUIをプロビジョニングしません。プレビューする対話出力を生成しないエージェントにこのフィールドを使用し、代わりにAPI を使用して呼び出します。デフォルトは `true` です。
`features.use_custom_parser`	ブール	no	の場合、カスタムストリーム出力が有効になります。修飾子に登録された `true`が必要です。パーサーを登録せずにこのフィールドを`OutputParser@app.output_parsertrue` に設定すると、エージェントの起動時に呼び出しは失敗します。詳しくは、「エージェントにカスタムストリーム出力を追加する」を参照してください。
`mcp.servers.<name>.transport`	string	`mcp.servers.<name>` が定義されている場合	リモート MCPサーバー接続のトランスポートプロトコル。使用可能な値はです。詳細については、「リモート MCP`streamable_http` サーバーの使用」を参照してください。
`mcp.servers.<name>.url`	string	`mcp.servers.<name>` が定義されている場合	リモート MCPサーバーエンドポイントのURL 。
`mcp.servers.<name>.headers`	map[string, string]	no	MCPサーバーへのすべてのリクエストで送信される静的HTTPヘッダー。
`mcp.servers.<name>.auth.type`	string	はい	認証タイプ。指定可能な値は `bearer_env` と `oauth` です。
`mcp.servers.<name>.auth.token_env`	string	`auth.type` が `bearer_env` の場合	Bearer トークンを保持する環境変数の名前。変数は `.env`ファイルに設定する必要があります。
`mcp.servers.<name>.auth.scope`	string	`auth.type` が `oauth` の場合	認可フロー中にリクエストスペース区切りの OAuth スコープ。
`mcp.servers.<name>.auth.client_name`	string	no	同意画面に表示される、人間が判読可能な OAuthクライアントの名前。
`mcp.servers.<name>.allowed_tools`	list[string]	no	エージェントに公開するリモート MCP ツール名の許可リスト。これを設定すると、プラットフォームはリストされているツールのみを登録し、サーバーが返す他のすべてのツールを無視します。省略した場合、プラットフォームはサーバーが返すすべてのツールを公開します。このフィールドを使用して、ツール画面をエージェントが必要とするツールのみに制限します。
`mcp.servers.<name>.timeout_seconds`	整数	no	MCP ツール呼び出しごとのリクエストタイムアウト（秒単位）。デフォルトは `30` です。
`scaling.replicas`	整数	no	配置の静的ポッド数。 Atlas Agent Engine は、この値をエージェントサンドボックスとツールサンドボックスに個別に適用します。各セッションでは、1 つのエージェントサンドボックスと、構成されている場合は 1 つのツールサンドボックスが予約されるため、この値は配置で提供できる同時セッションの数になります。 1 から 512 までの値を受け入れます。省略した場合、デフォルトは 4 になります。
`scaling.agent_idle_ttl_seconds`	整数	no	Atlas Agent Engine が他のセッションで再利用する前に、アイドルセッションが予約済みエージェントサンドボックスを保持する時間（秒単位）。 1 から 86400 までの値を受け入れます。省略した場合、デフォルトは 600 になります。 `scaling.agent_idle_ttl_seconds` はこのフィールドのレガシーエイリアスです。
`scaling.tool_idle_ttl_seconds`	整数	no	Atlas Agent Engine が再利用する前に、アイドルセッションが予約済みのツールサンドボックスを保持する時間（秒単位）。 1 から 86400 までの値を受け入れます。デフォルトは `scaling.agent_idle_ttl_seconds` 値です。
`sandboxes`	マッピング	はい	エージェントとそのツールを実行する名前付きサンドボックスを構成します。 Atlas Agent Engine は、`agent` との 2`tool` つの名前付きサンドボックスをサポートしています。追加のサンドボックスを定義することはできません。また、Atlas Agent Engine は複数のサンドボックスに割り当てられているツールを拒否します。サンドボックスがツール間でシークレットと出力先を共有する方法については、「 MongoDB Atlas Agent Engine の制限」を参照してください。
`sandboxes.agent`	マッピング	はい	エージェントサンドボックス（エージェントコードを実行するハードウェア分離されたサンドボックス）の構成。
`sandboxes.agent.secrets`	list[string]	no	エージェントサンドボックスで使用可能なシークレット名のリスト、またはシークレット名と一致するグローバルパターン。すべてのシークレットを一致させるには、`*` を使用します。 MONGODB_URI は自動的に使用可能であり、宣言する必要はありません。
`sandboxes.agent.tools`	list[string]	no	エージェントサンドボックスで実行するツール名のリスト、またはツール名と一致するグローバルパターン。すべてのツールに一致させるには、`*` を使用します。サンドボックスに一致するツールは、デフォルトでエージェントサンドボックスで実行されます。
`sandboxes.agent.network`	マッピング	no	エージェントサンドボックスのネットワークポリシー（アウトバウンド Egress ルールを含む）。詳細については、「ネットワーク Egress ポリシーの管理」を参照してください。
`sandboxes.tool`	マッピング	no	リモートツールボディを実行するハードウェア分離されたサンドボックスであるツールサンドボックスの構成。
`sandboxes.tool.secrets`	list[string]	no	ツールサンドボックスで使用できるシークレット名のリスト、またはシークレット名と一致するグローバルパターン。すべてのシークレットを一致させるには、を使用します。`*` MONGODB_URI は自動的に使用可能であり、宣言する必要はありません。
`sandboxes.tool.tools`	list[string]	no	ツールサンドボックスで実行するツール名のリスト、またはツール名と一致するグローバルパターン。すべてのツールに一致させるには、`*` を使用します。ツール本体から LM を呼び出すには、このリストに `invoke_llm` ツールを含め、`sandboxes.tool.secrets` の下で LM プロバイダーAPIキーを宣言します。
`artifact_repositories`	list[mapping]	no	マネージドビルドのプライベートパッケージレジストリを宣言します。各エントリは、レジストリインデックス名を、その認証情報を保持する Atlas Agent Engine のシークレットにマッピングします。 Atlas Agent Engine はビルド時にのみ認証情報を入力し、実行中のポッドには公開しません。レジストリ URL は、このブロックではなくプロジェクトツールに存在します（`pyproject.toml`、`package.json`、または `.npmrc`）。このフィールドを省略すると、Atlas Agent は既存のツール構成を変更せずに使用して、パブリックレジストリからの依存関係を解決します。
`artifact_repositories[].name`	string	はい	エントリのユニーク識別子。 PyPI エントリの場合、は `pyproject.toml` の `[[tool.uv.index]]` 名と一致する必要があります。 npmエントリの場合、検証は最初に `.npmrc` のスコープ付きレジストリに対して `npm_scope` を照合し、その後 `name` にフォールバックします。必ず `^[a-z][a-z0-9-]*$` と一致し、リスト内で一意である必要があります。
`artifact_repositories[].type`	string	はい	リポジトリタイプ。指定可能な値は `pypi` と `npm` です。
`artifact_repositories[].secret`	string	はい	認証情報を保持する Atlas Agent Engine シークレットの名前。 `^[A-Z][A-Z0-9_]{0,127}$` と一致する必要があります。
`artifact_repositories[].scope`	string	no	シークレットスコープ。指定可能な値は `project` と `workspace` です。デフォルトは `project` です。
`artifact_repositories[].auth`	string	no	認証方法。指定可能な値は `token` と `basic` です。デフォルトは `token` です。
`artifact_repositories[].username`	string	no	レジストリ認証のユーザー名。 `auth` が `basic` の場合に必須です。このフィールドが省略された PyPI トークン認証の場合、デフォルトは `__token__` です。 npm token auth ではユーザー名は使用されません。
`artifact_repositories[].npm_scope`	string	no	このレジストリにマッピングするnpmスコープ（`@acme` など）。指定した場合、`.npmrc` のスコープ付きレジストリに一致するキーです。 `type` が `npm` の場合にのみ有効です。

artifact_repositories 認証情報はビルド時にのみ解決されます。プライベートアーティファクトリポジトリがクラウドビルドとローカル開発でどのように機能するかについては、「エージェントイメージのビルド」と「エージェントをローカルで実行」を参照してください。

各セッションは有効期間中、独自のエージェントとツールのサンドボックスを予約し、Atlas Agent Engine はサンドボックスを新しいセッションに割り当てる前にサンドボックスをリセットします。その結果、1 つのセッションがサンドボックスに書き込むアーティファクトは、後のセッションには表示されません。

Atlas Agent Engine はビルド時に scaling の値をスナップショットするため、変更は次回のビルドと配置で有効になります。プラットフォームのデフォルトを変更しても、すでに配置されているワークスペースのサイズは変更されません。ワークスペースは、再度ビルドして配置するまで、最新のビルドからハードウェア分離されたサンドボックスのカウントを保持します。アイドル時間ライブ（TTL）の値はプロジェクト全体に適用されます。 1 つのプロジェクト内の複数のエージェントが異なる値を設定する場合、プロジェクトは最後に配置されたエージェントの値を適用します。

注意

ローカル開発設定は、dev.yaml agent.yaml自体ではなく、ファイルと同じディレクトリ内の別のagent.yaml ファイルで構成する必要があります。詳しくは、「ローカル開発設定の構成」を参照してください。

次の例では、サービスポートのオーバーライド、機能フラグ、シークレットアクセス制限、プライベートアーティファクトリポジトリを含む agent.yamlファイルを示しています。

name: my-agent
entrypoint: my_agent.main:app
features:
  guardrails: true
scaling:
  replicas: 4
  agent_idle_ttl_seconds: 900
  tool_idle_ttl_seconds: 300
sandboxes:
  agent:
    secrets: ["*"]
    tools: []
  tool:
    secrets:
      - SEARCH_API_KEY
      - ANTHROPIC_API_KEY
    tools:
      - my_search_tool
      - invoke_llm
artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN
    username: aws
    scope: project

MongoDB Manifest

リポジトリに複数のエージェントが含まれている場合は、最上位の agents: リストを使用して、単一の agent.yamlファイルでそれらを定義します。 Atlas Agent Engine はこのリストを検出し、ファイルを単一エージェント構成ではなく MongoDB マニフェストとして扱います。次の agent.yamlファイルは、複数のエージェントを含む MongoDB マニフェストの例です。

agents:
  - name: chat
    path: agents/chat
  - name: research
    path: agents/research

フィールド	タイプ	必須	説明
`agents[].name`	string	はい	エージェントの名前。小文字の英数字とハイフン文字のみを含める必要があります。先頭または末尾にはハイフンを使用しません。リスト内では一意である必要があります。
`agents[].path`	string	はい	リポジトリルートに対するエージェントのサブディレクトリへのパス。パスはリポジトリ以外のロケーションを参照はできません。

各エージェントサブディレクトリには、独自の単一エージェント agent.yamlファイルが含まれている必要があります。

.env の要件

dev.yamlファイルで services.mongodb.local が false に設定されている場合、エージェントを正常に配置するには、.envファイルで MONGODB_URI 環境変数を設定する必要があります。

また、実行時にリクエストを処理するには、{ファイルにLM APIキーが必要です。プラットフォーム自体は特定の.env LM 認証情報を検証したり要求したりしませんが、エージェントはその認証情報なしでは実行時に失敗します。<PROVIDER>_API_KEY LM プロバイダーの環境変数を設定するには、構文を使用します。

フレームワークと LM プロバイダー

このセクションでは、Atlas Agent Engine で使用できるフレームワークと LM プロバイダーについて説明します。

フレームワーク

Atlas Agent Engine は、 agent-engine-sdk-langgraphパッケージを通じて LagGraph と Lgachein をサポートします。フレームワークアダプターは、次の統合ポイントを処理します。

interrupt() 続行する前に人間によるレビューのためにエージェントの実行を一時停止するため
MongoDBSaver エージェントのグラフ状態をMongoDBに保存し、中断された実行が再開されたときに復元できるようにするため
LangChainInstrumentor デバッグとモニタリングのために実行中に LVM とツールの呼び出しを記録するため

LM プロバイダー

エージェントでは任意の LVM プロバイダーを使用できます。モデルを使用するには、プロバイダー用に Lgachein BaseChatModel を構築し、それを app.llm() メソッドに渡します。 Atlas エージェントエンジンは、オーケストレーションエンジンを介して呼び出しをルーティングします。

次の表は、環境キーと LgDBクラスを含む一般的なプロバイダーの例を示しています。

プロバイダー	環境キー	ラングチェーンクラス
OpenAI	`OPENAI_API_KEY`	`ChatOpenAI`
アナライザ	`ANTHROPIC_API_KEY`	`ChatAnthropic`
Gemini	`GEMINI_API_KEY` （任意: `GEMINI_MODEL`）	`ChatGoogleGenerativeAI`
Cerebras	`CEREBRAS_API_KEY` （任意: `CEREBRAS_MODEL`）	`ChatCerebras`

次のコード例は、app.llm() メソッドの各プロバイダーを構成する方法を示しています。

# OpenAI
from langchain_openai import ChatOpenAI
llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
# Anthropic
from langchain_anthropic import ChatAnthropic
llm = app.llm(ChatAnthropic(model="claude-sonnet-4-5"))
# Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
llm = app.llm(ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite"))
# Cerebras
from langchain_cerebras import ChatCerebras
llm = app.llm(ChatCerebras(model="qwen-3-235b-a22b-instruct-2507"))

次のステップ

配置されたエージェントを認証して呼び出す方法については、「エージェントの呼び出し」ガイドを参照してください。

パブリックプレビューの制限