Atlas 리소스 설정

프로필 파일 스키마

~/.agentengine/atlas.json 파일 구조는 다음과 같습니다.

{
  "version": 1,
  "profiles": {
    "default": {
      "base_url": "https://cloud.mongodb.com",
      "client_id": "<service-account-client-id>",
      "client_secret": "<service-account-client-secret>"
    }
  }
}

여러 개의 명명된 프로필을 추가하여 다양한 Atlas 환경 또는 서비스 계정과 함께 사용할 수 있습니다. 기본이 아닌 프로필을 사용하려면 다음 예시 와 같이 --profile 플래그를 전달합니다.

agentengine atlas setup --profile <profile-name>

환경 변수

프로필 파일 직접 편집하지 않고도 다음 환경 변수를 사용하여 자격 증명 제공하거나 재정의할 수 있습니다.

이 명령은 다음 순서로 자격 증명 확인합니다.

1. MONGODB_ATLAS_ACCESS_TOKEN, 설정하다 경우

2. MONGODB_ATLAS_CLIENT_ID 및 MONGODB_ATLAS_CLIENT_SECRET, 둘 다 설정하다 경우

3. 저장된 프로필 ~/.agentengine/atlas.json

4. 터미널이 연결된 경우 대화형 프롬프트

명령 플래그

인터랙티브 플로우

agentengine atlas setup를 실행 하면 CLI 다음 단계를 안내합니다.

1. 조직: 번호가 매겨진 메뉴와 함께 Atlas 조직을 나열합니다. 기존 조직 선택하거나 새 조직을 만듭니다.

2. 프로젝트: 선택한 조직 의 프로젝트를 나열합니다. 기존 프로젝트 선택하거나 새 프로젝트를 만듭니다. 새 프로젝트에는 프로젝트 범위의 서비스 계정이 제공됩니다.

3. 클러스터: 선택한 프로젝트 의 클러스터를 나열합니다. 기존 클러스터 를 선택하거나 서비스 계정에 클러스터 작성자 권한이 있는 경우 새 클러스터 만듭니다.

4. 데이터베이스 사용자: 에이전트 클러스터 에 연결하는 데 사용하는 자격 증명 사용하여 데이터베이스 사용자를 생성합니다.

5. Voyage AI API 키: 에이전트의 메모리 기능을 위한Voyage AI API 키를 프로비저닝합니다.

6. Secrets: 배포된 에이전트가 Atlas cluster 및 Voyage AI 에 연결할 수 있도록 MONGODB_URI 및 VOYAGE_API_KEY를 Atlas Agent Engine 시크릿으로 저장합니다.

7. IP 액세스 목록 : 클러스터의 IP 액세스 목록 에Atlas Agent Engine 데이터 플레인 IP 주소를 추가합니다.

흐름이 완료되면 CLI 에 각 리소스 에 대한 프로비저닝 상태가 표시됩니다.

자동 설정

대화형 프롬프트 없이 모든 Atlas 리소스를 자동으로 생성하려면 --yes 플래그를 agentengine atlas setup 명령에 전달합니다. 작업 공간이 초기화되지 않은 경우, agentengine atlas setup --yes 명령이 먼저 agentengine init를 실행한 다음, 작업 공간 ID 에 기반한 이름을 사용하여 다음 리소스를 생성합니다.

• Atlas cluster

• 데이터베이스 사용자 agent-engine-<workspace-id>

• 이름이 지정된 Voyage API 키 agent-engine-<workspace-id>

생성된 이름과 일치하는 저장된 메타데이터 또는 기존 Atlas 리소스를 찾으면 자동 설정 중지됩니다. 새 리소스 설정하다 를 생성하려면 충돌하는 리소스를 제거 하고 --force을 전달합니다.

자동 설정 저장된 Atlas 프로젝트 있는 경우 이를 사용합니다. 그렇지 않으면 메시지 없이 진행하려면 정확히 하나의 표시되는 Atlas 조직 과 하나의 표시되는 Atlas 프로젝트 필요합니다.

명령을 실행 전에 다음 환경 변수를 설정하여 기본값 클러스터 구성을 재정의할 수 있습니다.

설정 상태

agentengine atlas setup 명령은 각 실행 끝날 때 모든 리소스의 프로비저닝 상태를 표시합니다. 현재 상태 다시 확인하거나 전체 설정 흐름을 다시 실행하려면 다음 명령을 실행 .

agentengine atlas setup --force

프로필 나열

다음 명령을 사용하여 ~/.agentengine/atlas.json 파일 에서 저장된 프로필을 반환합니다.

agentengine atlas profile list --json

다음 예시 출력 형식을 보여줍니다.

{
  "schema_version": "1",
  "status": "ok",
  "profiles": [
    {"name": "default", "base_url": "https://cloud.mongodb.com"}
  ]
}

프로필 확인

다음 명령을 사용하여 서비스 계정 자격 증명 유효성을 검사하고 액세스 가능한 조직 및 프로젝트를 반환합니다.

agentengine atlas profile verify --json --input -

-을 --input 플래그에 전달하여 stdin를 통해 JSON 요청 객체 전달합니다. 이 명령은 선택한 프로필 이름, 기본 URL, 액세스 가능한 조직 및 프로젝트 목록을 반환합니다. 출력에는 액세스 토큰과 시크릿이 포함되지 않습니다.

프로필 저장

선택한 Atlas 조직 및 프로젝트 작업 공간 컨텍스트에 유지하려면 다음 명령을 사용합니다.

agentengine atlas profile save [--context <name>] [--workspace <name>] --json --input -

-을 --input 플래그에 전달하여 stdin를 통해 JSON 요청 객체 전달합니다. 이 명령은 Atlas 환경, 프로필, 조직 및 프로젝트 작업 공간의 .agentengine/state.json 파일 에 저장합니다. 조직 및 프로젝트 선택이 변경되지 않는 경우 이 명령은 기존 클러스터, 데이터베이스 사용자 및 Voyage API 키 선택을 모두 유지합니다.

클러스터 나열

다음 명령어를 사용하여 저장된 Atlas 프로젝트 의 클러스터를 반환합니다.

agentengine atlas cluster list [--context <name>] [--workspace <name>] --json

다음 예시 출력 형식을 보여줍니다.

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "clusters": [
    {
      "name": "my-cluster",
      "kind": "REPLICASET",
      "state_name": "IDLE",
      "is_flex": false
    }
  ],
  "create_defaults": {
    "name": "my-agent",
    "provider": "AWS",
    "region": "US_EAST_1",
    "tier": "FLEX",
    "label": "Flex"
  },
  "can_create": true,
  "warnings": []
}

create_defaults 객체 새 클러스터 에 대한 추천 구성을 제공합니다. can_create 필드 서비스 계정에 선택한 프로젝트 에서 클러스터 생성할 수 있는 권한이 있는지 여부를 나타냅니다.

클러스터 저장

다음 명령을 사용하여 기존 클러스터 선택하거나 새 클러스터를 생성합니다.

agentengine atlas cluster save [--context <name>] [--workspace <name>] --json --input -

-을 --input 플래그에 전달하여 stdin를 통해 JSON 요청 객체 전달합니다. 기존 클러스터 선택하려면 다음을 수행합니다.

{"mode": "existing", "name": "my-cluster"}

새 클러스터 만들려면 다음을 수행합니다.

{
  "mode": "create",
  "name": "my-agent",
  "provider": "AWS",
  "region": "US_EAST_1",
  "tier": "FLEX"
}

생성 모드 에서 name 필드 생략하면 CLI 작업 공간 ID 에서 이름을 생성합니다. 클러스터 생성하면 Atlas 에서 프로비저닝 요청되고 즉시 반환됩니다. Atlas 클러스터 프로비저닝 완료하는 데 몇 분 정도 걸릴 수 있습니다.

데이터베이스 사용자 나열

저장된 Atlas 프로젝트 에서 데이터베이스 사용자를 반환하려면 다음 명령을 사용합니다.

agentengine atlas database-user list [--context <name>] [--workspace <name>] --json

다음 예시 출력 형식을 보여줍니다.

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "users": [
    {"username": "my-user", "database_name": "admin"}
  ],
  "create_defaults": {"username": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

명령이 작업 공간에 대해 생성된 기본값 과 이름이 일치하는 기존 사용자를 찾으면 해당 사용자를 .agentengine/state.json 파일 에 자동으로 저장합니다. 이렇게 하면 현재 세션 외부에서 리소스가 프로비저닝되었을 때 상태 상태를 최신 상태로 유지합니다.

데이터베이스 사용자 저장

다음 명령을 사용하여 기존 사용자를 선택하거나 새 사용자를 생성합니다.

agentengine atlas database-user save [--context <name>] [--workspace <name>] --json --input -

-을 --input 플래그에 전달하여 stdin를 통해 JSON 요청 객체 전달합니다. 기존 사용자를 선택하려면 다음 예시 에 표시된 대로 비밀번호를 포함합니다.

{"mode": "existing", "username": "my-user", "password": "my-password"}

새 사용자를 만들려면 다음 객체 전달합니다.

{"mode": "create", "username": "my-user"}

생성 모드 에서 username 필드 생략하면 CLI 작업 공간 ID 에서 이름을 생성합니다. 신규 사용자의 경우 CLI 비밀번호를 자동으로 생성합니다. 생성된 비밀번호는 명령 출력에 포함되지 않습니다.

저장 후 명령은 MONGODB_URI을 프로젝트 범위 Atlas Agent Engine 시크릿으로 씁니다. 로컬 파일 에는 쓰기 (write) 않습니다.

Voyage API 키 나열

다음 명령어를 사용하여 저장된 Atlas 프로젝트 에서 Voyage API 키를 반환합니다.

agentengine atlas voyage-api-key list [--context <name>] [--workspace <name>] --json

다음 예시 출력 형식을 보여줍니다.

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "keys": [
    {
      "id": "key-id",
      "name": "agent-engine-<workspace-id>",
      "masked_secret": "voy...xxxx"
    }
  ],
  "create_defaults": {"name": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

명령이 작업 공간에 대해 생성된 기본값 과 이름이 일치하는 기존 키를 찾으면 해당 키를 .agentengine/state.json 파일 에 자동으로 저장합니다.

Voyage API 키 저장

다음 명령을 사용하여 기존 키를 선택하거나 새 키를 생성합니다.

agentengine atlas voyage-api-key save [--context <name>] [--workspace <name>] --json --input -

-을 --input 플래그에 전달하여 stdin를 통해 JSON 객체 전달합니다. 기존 키를 선택하려면 다음 형식을 사용합니다.

{"mode": "existing", "name": "my-key", "value": "<api-key-value>"}

새 키를 만들려면 다음 형식을 사용하세요.

{"mode": "create", "name": "my-key"}

생성 모드 에서 name 필드 생략하면 CLI 작업 공간 ID 에서 이름을 생성합니다. 키를 생성하면 CLI Atlas에서 반환한 시크릿 값을 직접 사용합니다.

저장 후 명령은 VOYAGE_API_KEY을 프로젝트 범위 Atlas Agent Engine 시크릿으로 씁니다. 로컬 파일 에는 쓰기 (write) 않습니다. 하위 Atlas 환경의 경우 이 명령은 VOYAGE_URL 변수도 동일한 방식으로 씁니다.