エージェントをローカルで実行およびテストする

メモリを有効にする

agent.yamlファイルで features.memory: true を設定する場合は、ローカル環境を起動する前に、次の変数を .envファイルに追加します。

• VOYAGE_API_KEY: メモリ埋め込みの生成に必要です。

• MONGOMEM_DB_NAME: 任意。メモリサーバーが書き込むMongoDBデータベース名。デフォルトは mdb_memory_<project-id> です。

ローカル開発設定の構成

dev.yamlファイルを使用してローカル サービス ポートの割り当てを上書きし、開発中にローカルMongoDBインスタンスをオンまたはオフにすることができます。 dev.yamlファイルをagent.yamlファイルと同じディレクトリに配置します。このファイルは任意であり、プラットフォームはこのファイルを .gitignoreファイルに追加しないため、設定をコミットして共有できます。

次の表では、dev.yamlファイルに含めることができるフィールドを説明しています。

次の例は、利用可能なすべてのフィールドを設定する dev.yamlファイルを示しています。

services:
  playground:
    port: 3000
  oe:
    port: 8000
  aer:
    port: 8001
  tool:
    port: 8002
  mongodb:
    local: true
    port: 27017

ホットリロードモード（推奨）

ホットリロードモードでは、すべてのエージェントサービスが単一のアプリコンテナ内で実行され、ソースコードが直接マウントされます。ファイルを編集すると、監視ファイルによって変更が検出され、影響を受けるサービスが自動的に再読み込みされます。完全な再構築は必要ありません。

agentengine dev up

分離モード

--isolated フラグを使用して、ローカル環境を 分離モードで起動できます。分離モードでは、 本番環境のトポロジーをミラーリングして、 個別のコンテナ内で各エージェントサービスを起動します。このモードを使用して、サービス境界全体の動作を検証したり、本番固有の問題を再現したりします。コードはホストからマウントされていないため、コードを変更した後にイメージを再ビルドする必要があります。

agentengine dev up --isolated

agentengine dev stop
agentengine dev up --isolated

ログの表示

実行中のすべてのサービスからログをストリーミングするには、次のコマンドを実行します。

agentengine dev logs

特定のサービスからログをストリーミングするには、サービス名を位置引数として渡します。

agentengine dev logs <service>

単一リポジトリでは、--all を渡して、共有すべてのワークスペーススタックのログをストリーミングします。

agentengine dev logs --all

ローカル スタックのステータス確認

agentengine dev status コマンドは、サービスごとのステータスや公開ホスト URL など、ローカル コンフィギュレーションスタックの現在の状態を表示します。以下の例では、コマンド構文を示しています。

agentengine dev status [--workspace <name>] [--all] [--json]

次の表では、使用可能なフラグについて説明しています。

サービスを再起動する

agentengine dev restart コマンドは、イメージを再ビルドせずにホットリロード app コンテナと oe コンテナを再起動します。ホストの依存関係を変更した後にこれを使用します。以下の例では、コマンド構文を示しています。

agentengine dev restart [--workspace <name>]

このコマンドは、ホットリロードスタックのみを対象とします。 --all または 分離モードはサポートされていません。

新しい依存関係の追加

pyproject.tomlファイルに依存関係を追加する場合、uv.lockファイルがすでに存在する場合は、ローカル開発スタックによってその依存関係がインストールされない可能性があります。 uv.lockファイルが存在する場合、開発エントリポイントは --frozen フラグで環境を同期します。これにより、pyproject.tomlファイルではなくロックファイルから依存関係が解決されます。

新しい依存関係をインストールするには、次のコマンドを実行して uv.lockファイルを削除し、スタックを再起動します。

rm uv.lock
agentengine dev stop
agentengine dev up

または、スタックを再起動する前に、次のコマンドを実行してロックファイルを更新することもできます。

uv lock
agentengine dev stop
agentengine dev up

プライベート アーティファクト リポジトリの使用

エージェントが、 AWS CodeAtlas のプライベート PyPI やnpmレジストリなどのプライベート アーティファクト リポジトリでホストされているパッケージに依存している場合は、 agent.yamlファイルの artifact_repositories ブロックでそれらを宣言します。ホットリロードモードでは、agentengine dev up コマンドと agentengine dev restart コマンドによって、type: pypi エントリのレジストリ認証情報が自動的に構成されます。 CLI はnpmエントリを自動構成しません。 npmプライベート依存関係の場合は、 プロジェクト レベルの .npmrcファイルなどのローカルnpm構成を介して認証します。

宣言された PyPIリポジトリごとに、次のいずれかの方法で認証情報を提供します。

• プロセス環境または .envファイル内の UV_INDEX_<NAME>_PASSWORD（およびオプションで _USERNAME）変数。例、corps-pypi という名前のインデックスには UV_INDEX_CORPS_PYPI_PASSWORD を設定します。

• 宣言された secretフィールド。これは .envファイルから読み取られます。

• AWS CodeAtlasインデックスの場合、アクティブなAWSプロファイルまたは SSO セッションから生成されたトークン。

宣言されたリポジトリの認証情報が解決されない場合、CLI は失敗し、確認するリポジトリとソースに名前を付けます。

自動構成をスキップして、UV_INDEX_* 変数を自分で管理するには、次のコマンドを実行します。

agentengine dev up --no-artifact-auth

artifact_repositoriesスキーマの詳細については、「 エージェント YAML スキーマ 」を参照してください。プライベート アーティファクト リポジトリがクラウドビルドでどのように機能するかについては、「 プライベート アーティファクト リポジトリ 」を参照してください。

サービスの停止

コンテナを削除せずにローカル環境を一時停止するには、次のコマンドを実行します。

agentengine dev stop [--workspace <name>] [--all]

コマンドは、コンテナを削除せずに停止します。リビルドせずにコンテナを再開するには、agentengine dev up を再度実行します。

ローカル状態のリセット

すべてのコンテナを停止し、関連するボリュームと生成されたランタイム ファイルをすべて削除するには、次のコマンドを実行します。

agentengine dev clean [--workspace <name>] [--all]

消去後に agentengine dev up を実行してファイルを再生成し、新しいローカル コンテナを起動します。

リモート MCP サーバーの認証

agentengine dev mcp auth コマンドは、mcp.servers の下の agent.yamlファイルに構成されたリモート MCP サーバーの OAuth 認証情報を管理します。コマンドはログイン認証情報を ~/.agentengine/mcp-oauth の開発者認証キャッシュに書き込み、生成された agentengine dev up スタックはそのディレクトリを自動的にマウントします。

キャッシュはプロジェクトごとと MCP エンドポイントごとに異なります。あるプロジェクトからログインしても、別のプロジェクトにはログしないため、プロジェクトごとにagentengine dev mcp auth login 1 回 コマンドを実行する必要があります。 MCP サーバーの命名要件の詳細については、「 サーバーの命名規則 」を参照してください。

agentengine dev mcp auth login <server> [--no-browser]

agentengine dev mcp auth status [server] [--check]

agentengine dev mcp auth upload <server> [--workspace-id <id>] [--sync]