개요
이 튜토리얼에서는 MongoDB Atlas Agent Engine을 사용하여 계정을 설치하고 인증하는 방법을 보여줍니다. 시스템 종속성을 확인하고, agentengine CLI 설치하고, 러너 기반 이미지를 확인하고, Atlas Agent Engine API 게이트웨이에 대해 계정을 인증합니다.
전제 조건
이 튜토리얼을 시작하기 전에 다음 구성 요소가 설치 및 구성되어 있는지 확인하십시오.
전제 조건 | 참고 사항 |
|---|---|
지원되는 운영 체제 | 지원되는 운영 체제는 다음과 같습니다.
|
컨테이너 엔진 | 컴퓨터에서 활발하게 실행 Docker Compose v2와 함께 Docker Desktop 또는 Docker Engine을 사용하세요. Atlas Agent Engine은 최선의 방식으로 Podman을 지원하며, CLI |
버전 3.11 이상을 사용하세요. | |
MongoDB cluster | 배포된 에이전트 는 이 클러스터 사용하므로 해당 연결 문자열 조회 해야 합니다. 로컬 테스트는 자체 MongoDB 컨테이너 시작합니다. |
네트워크 액세스 | 네트워크에서 다음 호스트에 대한 아웃바운드 액세스 허용해야 합니다.
CLI 에어 갭 또는 이그레스 제한 네트워크의 경우, 제어하는 호스트에서 CLI 바이너리 및 에이전트 런타임 이미지를 소싱할 수 있습니다. 사용자 지정 아티팩트 소스를 구성하는 방법을 학습 보려면 사용자 지정 아티팩트 소스 사용을 참조하세요. |
사용자 지정 아티팩트 소스 사용
MongoDB 에서 호스팅하는 레지스트리 대신 자체 호스트에서 바이너리 및 가져오기 에이전트 런타임 이미지를 다운로드 하도록 agentengine CLI 구성할 수 있습니다. agentengine agent source setup를 실행하여 source.yaml 파일 생성하거나 agentengine agent source template를 실행 편집할 수 있는 주석 처리된 템플릿을 쓰기 (write) . 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 차단 에이전트 런타임 이미지를 레지스트리로 가져옵니다. 이 중 하나만 미러링하는 경우, CLI 다른 base 소스인 internal을 기본값 으로 사용합니다.
type: static을 사용하는 경우, release.url의 매니페스트는 각 OS 및 아키텍처에 대해 assets에 하나의 항목이 있는 다음 구조와 일치해야 합니다. 그렇지 않으면 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를 https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases와 같은 API 엔드포인트로 설정합니다.
이미지 레지스트리에 인증 필요한 경우 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
agentengine CLI 설치
agentengine CLI 는 MongoDB Atlas Agent Engine을 사용한 로컬 개발을 위한 프라이머리 도구입니다. 에이전트의 세 가지 서비스를 로컬에서 실행 데 필요한 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 설치되었는지 확인합니다.
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이 에이전트의 세 가지 서비스 각각을 로컬에서 실행 데 사용하는 컨테이너 이미지입니다. 에이전트 처음 실행 때 Docker 이 이미지를 가져올 수 없으면 에이전트 시작되지 않습니다. Docker 기본 이미지를 확인하면 에이전트 프로젝트 실행 전에 네트워크 문제를 파악하고 해결할 수 있습니다. 러너 기반 이미지를 확인하는 것은 선택 사항이지만 권장됩니다.
로컬 개발은 MongoDB의 호스팅된 컨테이너 이미지 레지스트리에서 러너 기반 이미지를 가져옵니다. GitHub 액세스 나 별도의 레지스트리 로그인이 필요하지 않습니다. CLI agentengine auth login 세션을 사용하여 이미지를 조회 하고, agentengine dev up 명령을 실행 때 레지스트리 호스팅하다 인쇄합니다.
계정 인증
agentengine auth login 명령은 Atlas Agent Engine API 게이트웨이에 대한 브라우저 기반 OIDC 로그인 흐름을 시작하고 향후 CLI 명령을 위해 로컬 인증 상태 저장합니다.
참고
Atlas OAuth 위임
Atlas Agent Engine에 로그인하면 플랫폼이 자동으로 Atlas 에서 역할 할당을 검색하고 사용자가 액세스 할 수 있는 조직 및 프로젝트를 결정합니다. 이 플랫폼은 Atlas OAuth 2.1 앱 연결 서버 사용하여 Atlas 에 대한 액세스 권한을 부여합니다.
Atlas Agent Engine에 로그인합니다.
터미널에서 다음 명령을 실행 .
agentengine auth login
기본값 으로 https://agentengine.mongodb.com에서 프로덕션 API 게이트웨이에 대한 브라우저가 열립니다. 명령에 --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, 기본값 조직 및 프로젝트 계속 표시됩니다.
팁
인증 토큰이 만료되면 로그 아웃했다가 다시 로그 새로 고침하세요.
agentengine auth logout agentengine auth login
다음 단계
MongoDB Atlas Agent Engine을 사용하여 계정을 설치하고 인증한 후 프로젝트 만들 수 있습니다. 다음 단계를 수행하는 방법을 학습 프로젝트 만들기 가이드 참조하세요.