Overview
このチュートリアルでは、MongoDB Atlas Agent Engine を使用してアカウントをインストールおよび認証する方法を説明します。システム依存関係を検証し、agentengine CLI をインストールし、ランサー ベースのイメージを検証し、Atlas Agent Engine API Gateway に対してアカウントを認証します。
前提条件
このチュートリアルを開始する前に、次のコンポーネントがインストールと構成されていることを確認してください。
前提条件 | ノート |
|---|---|
サポートされているオペレーティングシステム | 次のオペレーティング システムがサポートされています。
|
コンテナエンジン | マシン上でDocker Compose v がアクティブに実行中状態で、 Docker Desktop またはDocker Engine2 を使用します。 Atlas エージェント エンジンは Podman をベストエフォートベースでサポートしており、CLI は |
バージョン 3.11 以降を使用します。 | |
MongoDBクラスター | 配置されたエージェントはこのクラスターを使用するため、その接続文字列を取得する必要があります。ローカル テストは独自のMongoDBコンテナを起動します。 |
ネットワークアクセス | ネットワークでは、次のホストへのアウトバウンド アクセスが許可されている必要があります。
CLI は、 ポリゴンまたは Egress が制限されたネットワークの場合は、管理するホストから CLI バイナリとエージェントのランタイム イメージを取得できます。カスタム アーティファクト ソースの構成方法については、「 カスタム アーティファクト ソースの使用 」を参照してください。 |
カスタム アーティファクト ソースの使用
agentengine CLI を構成して、 MongoDBホスト型レジストリではなく、自分のホストからバイナリとプルエージェントのランタイム イメージをダウンロードできます。 agentengine agent source setup を実行して source.yamlファイルを生成するか、agentengine agent source template を実行してコメント付きテンプレートを作成し、編集できるようにします。 agentengine CLI をインストールした後にこれらのコマンドを実行します。
デフォルトでは 、CLI は ~/.agentengine/source.yaml から source.yaml を読み取ります。別の場所を使用するには、AGENTENGINE_IMAGE_SOURCE_FILE 環境変数をファイルパスに設定します。
AGENTENGINE_IMAGE_SOURCE=custom をエクスポートして、agentengine dev up と agentengine self-update をカスタム ホストにルーティングします。次のサンプルsource.yaml は、CLI バイナリとエージェントのランタイム イメージの両方をミラーリングします。
base: internal release: type: static url: https://artifactory.example.com/agentic-cli/manifest.json registry: prefix: artifactory.example.com/acme-docker
release ブロックは CLI バイナリのダウンロードをホストに指示し、registry.prefix ブロックはエージェントのランタイム イメージをレジストリにプルします。これらの 1 つだけをミラーリングした場合、CLI は他のソースにも base ソース（デフォルトでは internal を使用します）。
type: static を使用する場合、release.url のマニフェストは次の構造と一致する必要があり、OS とアーキテクチャごとに assets に 1 つのエントリが含まれます。それ以外の場合は、agentengine self-update が失敗し、CLI は更新通知を表示しません。
{ "releases": [ { "version": "1.4.2", "assets": [ { "os": "darwin", "arch": "arm64", "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64", "sha256": "9f2b...e1" } ] } ] }
マニフェストではなく GitHub Enterprise リリースAPIからのリリースを読み取るには、release.type を github に設定し、release.url をAPIエンドポイント（https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases など）に設定します。
イメージ レジストリで認証が必要な場合は、agentengine dev up を実行する前にログしてください。例、docker login <registry> を実行するか、 Amazon ECR の場合は次のコマンドを実行します。
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com
CLI をインストールするagentengine
agentengine CLI は、 MongoDB Atlas Agent Engine を使用したローカル開発用のプライマリ ツールです。これは、エージェントの 3 つのサービスをローカルに実行するために必要なDocker Compose 構成を生成します。
次の手順では、 Atlas Agent Engine UIから CLI をダウンロードする方法について説明します。
[ CLI のインストール ] ページを開きます。
Atlas Agent Engine にサインインし、 CLI ダウンロード ページ から CLI をダウンロードします。
ページには、最新の CLI バージョンが事前に入力されている Version ドロップダウンが表示されます。また、検出されたオペレーティング システムが事前に入力された Platform ドロップダウンも表示されます。これらのデフォルト値を変更するには、ドロップダウン セレクターから別のバージョンまたはプラットフォームを選択します。
バイナリをPATH に追加します。
バイナリを PATH に追加する手順を表示するには、オペレーティング システムに対応するタブを選択します。
ダウンロードディレクトリから、次のコマンドを実行します。
mkdir -p ~/.local/bin mv agentengine ~/.local/bin/agentengine
~/.local/bin が PATH にあることを確認します。ユーザーが書き込み可能なディレクトリにバイナリをインストールすると、sudo コマンドを使用せずに agentengine self-update コマンドを実行できます。
.exeファイルをPATH にすでにあるディレクトリに移動するか、そのディレクトリをSystem Properties に追加します -> Environment
Variables -> Windows GUI での Path。
agentengine コマンドを使用するには、バイナリの名前を agentengine.exe に変更します。
インストールを確認します。
CLI のバージョンをチェックして、CLI がインストールされていることを確認します。
agentengine version
出力は次のようになります。
0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry-host>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry-host>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry-host>/playground-ui:0.1.94-alpha orchestrator: <registry-host>/orchestration-engine:<version> memory-server: <registry-host>/memory-server:<version>
インストール済みの CLI を新しいバージョンに更新する方法については、「 CLI の更新 」を参照してください。
ランサーベースのイメージを検証します
ルーターベースのイメージは、Atlas Agent Engine が各エージェントの 3 つのサービスをローカルに実行するために使用するコンテナのイメージです。エージェントを初めて実行するときにDocker がこのイメージをプルできない場合、エージェントは起動に失敗します。 Dockerベースイメージを検証することで、エージェントプロジェクト を実行する前にネットワークの問題をキャッチして修正できます。ドライバーベースのイメージを検証することは任意ですが、推奨されます。
ローカル開発では、MongoDB のホスト型コンテナイメージ レジストリからドライバー ベース イメージをプルします。 GitHubアクセスや別のレジストリログインは必要ありません。 CLI は agentengine auth login セッションを使用してイメージを取得し、agentengine dev up コマンドを実行するとレジストリ ホストを出力します。
アカウントの認証
agentengine auth login コマンドは、Atlas Agent Engine API Gateway に対してブラウザベースの OIDC ログイン フローを開始し、将来の CLI コマンドのローカル認証状態を保存します。
注意
Atlas OAuth の削除
Atlas Agent Engine にサインインすると、プラットフォームは Atlas から自動的にロールの割り当てを取得し、ユーザーがアクセスできる組織とプロジェクトを決定します。プラットフォームは、Atlas OAuth 2.1 App Connectionsサーバーを使用して Atlas へのアクセスを許可します。
Atlas Agent Engine にログインします。
ターミナルから、次のコマンドを実行します。
agentengine auth login
デフォルトでは 、これにより、https://agentengine.mongodb.comの本番API Gateway に対してブラウザが開きます。コマンドに --base-url を渡して別のゲートウェイをターゲットにするか、--no-browser を渡してブラウザを開かずにログインURLを出力できます。次のコードは、 コマンドの形式を示しています。
agentengine auth login [--base-url <url>] [--no-browser] [--timeout <duration>]
サインインが完了すると、CLI はAPIからプロジェクトメンバーシップを読み取り、選択したプロジェクトID project_id と認証トークンを保持します。
認証状態を確認します。
認証が成功したかどうかを確認するには、次のコマンドを実行します。
agentengine auth status
このコマンドは、プラットフォームにアクセスせずに現在のローカル認証コンテキストを出力します。その出力は、ディスクに保存されているログイン状態を反映します。コマンドに --json フラグを渡すと、auth、command_defaults、directory_context フィールドを個別に含むJSONオブジェクトを出力できます。
agentengine init コマンドを実行中してエージェントディレクトリを登録するまで、Directory contextフィールドはnone found を報告します。ログインに成功しても、アカウント、ベースURL、デフォルトの組織とプロジェクト は表示されます。
Tip
認証トークンの有効期限が切れた場合は、ログして再ログて更新します。
agentengine auth logout agentengine auth login
次のステップ
MongoDB Atlas Agent Engine を使用してアカウントをインストールして認証したら、プロジェクトを作成 できます。これらの次の手順を実行する方法については、 「プロジェクトの作成」ガイドを 参照してください。