개요
이 가이드 에서는 CLI 에서 에이전트 이미지를 빌드 방법을 학습 수 있습니다. 빌드 프로세스 에이전트 소스 코드 cloud 저장 에 업로드하고 Docker 이미지를 생성하는 원격 빌드 작업 시작합니다.
빌드 명령 구문 및 옵션
다음 구문을 사용하여 에이전트 이미지를 빌드 .
agentengine build [--label <str>] [--no-wait] [--context <name>] [--workspace <name>] [--all] [--json] [--upload-build-secrets]
이 명령은 에이전트 소스를 tar.gz 파일 로 패키징하고, 미리 서명된 URL 통해 S3(Simple Storage Service) 버킷에 업로드한 다음, AWS Docker 작업 시작하여 Elastic Container Registry( ECR).
명령 플래그
에이전트 이미지를 빌드할 때 다음과 같은 선택적 플래그를 사용할 수 있습니다.
플래그 | 설명 |
|---|---|
| 빌드 레이블입니다. 기본값 으로 이 값은 |
| 빌드 상태를 폴링하지 않고 빌드 작업 시작한 후 즉시 반환하도록 CLI 에 지시합니다. |
|
|
| (Monorepo에만 해당) 루트 |
| (Monorepo에만 해당) 모든 작업 공간을 순차적으로 빌드합니다. CLI 소스 아카이브를 한 번 생성한 다음 각 작업 공간에 대해 업로드 및 빌드 단계를 실행합니다. 모든 빌드가 시작되면 터미널 상태에 도달할 때까지 각 빌드 폴링합니다. 이 플래그는 |
| 기계가 읽을 수 있는 단일 빌드 결과를 출력합니다. |
| 빌드 시작되기 전에 동일한 이름의 환경 변수에서 |
콘텐츠 보관
에이전트 소스를 업로드하기 전에 CLI 이전 섹션에서 참조된 tar.gz 아카이브를 빌드합니다. 이 섹션에서는 아카이브가 패키지하는 디렉토리 와 제외하는 파일에 대해 설명합니다.
보관 루트
기본값 으로 agentengine build 명령은 에이전트 디렉토리 만 패키징합니다. 작업 공간 또는 모노 리포지토리 구성 파일 에이전트 디렉토리 멤버로 나열하는 경우 명령은 대신 작업 공간 또는 모노 리포지토리 루트에서 패키지를 만듭니다. 목록 요구 사항은 다음 표에 설명된 대로 작업 공간 유형에 따라 다릅니다.
작업 공간 유형 | 멤버십 요건 |
|---|---|
uv 작업 공간 | 에이전트 디렉토리 |
Monorepo | 에이전트 디렉토리 루트 |
작업 공간 또는 모노리포지토리 루트를 찾기 위해 CLI 에이전트 디렉토리의 상위 디렉토리를 통해 루트를 표시하는 파일 위쪽으로 검색합니다. 검색 은 git 리포지토리의 루트 디렉토리 에서 중지되고 홈 디렉토리 로 계속 이동하지 않으므로 이 명령은 리포지토리 외부의 파일을 패키지 할 수 없습니다.
에이전트 디렉토리 가 git 하위 모듈 또는 연결된 작업 트리인 경우 검색 해당 경계에서 중지되지 않습니다. 검색 은 상위 리포지토리 로 계속되며 앞의 표에 설명된 멤버십 규칙에 따라 명령이 패키지를 생성하는 디렉토리 결정됩니다.
제외된 파일
아카이브 루트의 프로젝트 수준 .agentengineignore 파일 CLI 가 아카이브에 압축할 파일을 제어합니다. 이 파일 glob, ** 및 ! 부정을 포함한 표준 .gitignore 구문을 사용합니다. agentengine init 명령은 다음과 같은 기본값 패턴으로 파일 생성합니다.
.git.venv*__pycache__.pytest_cache.mypy_cache.ruff_cachenode_modulesdistbuild.agentengine*.pyc.env.env.*.DS_Store*.pem*.key
파일 없는 경우 CLI agentengine init 명령과 동일한 기본값 패턴을 사용합니다.
다음 파일은 항상 제외되며, .agentengineignore 파일 에서 ! 부정을 사용하여 이를 재정의할 수 없습니다.
.env및.env.*파일*.pem및*.key파일일반적인 OpenSSH 비공개 키:
id_rsa,id_dsa,id_ecdsa,id_ed25519,id_ed448.git디렉토리클라우드 및 도구 자격 증명 저장소:
.aws,.kube,.ssh,.netrc,.git-credentials,.azure,.config/gh,.docker/config.json,.config/gcloud
프로젝트 수준 .npmrc 파일 이 제외된 파일 설정하다 에 포함되지 않습니다. 플랫폼 빌드 아카이브에서 .npmrc 파일 읽어 선언된 비공개 npm 레지스트리를 확인합니다. 이 빌드 또한 pyproject.toml를 읽어 선언된 비공개 PyPI 레지스트리를 확인합니다. 빌드 에 대한 비공개 레지스트리 자격 증명 구성하는 방법을 학습 비공개 아티팩트 리포지토리를 참조하세요.
경고
빌드 .npmrc 및 pyproject.toml 파일이 포함되어 있으므로 해당 파일에 레지스트리 토큰이나 자격 증명 저장 하지 마세요. 대신 agent.yaml 파일 의 artifact_repositories에서 자격 증명 선언합니다. 자세한 학습 은 비공개 아티팩트 리포지토리를 참조하세요.
비공개 아티팩트 리포지토리
에이전트 AWS CodeArtifactor와 같은 비공개 아티팩트 리포지토리에 호스팅된 패키지에 의존하는 경우, agent.yaml 파일 의 artifact_repositories 차단 에서 해당 리포지토리를 선언합니다. Atlas Agent Engine은 빌드 시 각 항목에 명명된 Atlas Agent Engine 시크릿에서 레지스트리 자격 증명 확인하고 이를 빌드 환경에 삽입합니다. 자격 증명 소스 파일에 저장되지 않으며 실행 파드에 노출되지 않습니다. 리포지토리를 선언하지 않으면 Atlas Agent Engine은 기존 도구 구성을 사용하여 공개 레지스트리의 종속성을 변경하지 않고 확인합니다.
레지스트리 URL은 agent.yaml이 아닌 프로젝트 도구에 있습니다. Python 에이전트의 경우 pyproject.toml의 [[tool.uv.index]] 항목에서 각 비공개 인덱스 선언합니다. agent.yaml의 name 필드 인덱스 이름과 일치해야 합니다. TypeScript 에이전트의 경우 .npmrc 파일 에서 각 비공개 범위 레지스트리를 선언합니다. agent.yaml의 npm_scope를 레지스트리에 매핑되는 범위로 설정합니다. 다음 예시는 각 언어 에 대해 일치하는 도구 파일 과 agent.yaml 항목을 보여줍니다.
[[tool.uv.index]] name = "corps-pypi" url = "https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com/pypi/<repo>/simple/" explicit = true
artifact_repositories: - name: corps-pypi type: pypi secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN username: aws scope: project
@acme:registry=https://npm.pkg.github.com/
artifact_repositories: - name: corp-npm type: npm secret: ARTIFACT_REPO_CORP_NPM_TOKEN npm_scope: "@acme" scope: project
전체 artifact_repositories 스키마 에 대해 학습 에이전트 YAML 스키마를 참조하세요.
Atlas Agent Engine은 빌드 시작되기 전에 프로젝트 도구를 기준으로 선언된 리포지토리의 유효성을 검사합니다. 유효성 검사 실패하면 실행 가능한 오류와 함께 빌드 중지됩니다. 빌드하기 전에 문제를 파악하려면 로컬에서 agentengine agent validate를 실행 . 자세히 학습 구성 유효성 검사를 참조하세요.
선언된 각 artifact_repositories[].secret는 빌드 시작되기 전에 Atlas Agent Engine 시크릿의 선언된 범위에 존재해야 합니다. 빌드 사이에 만료되는 단기 레지스트리 토큰의 경우, --upload-build-secrets 플래그를 사용하여 동일한 이름의 환경 변수에서 각 시크릿을 업로드하세요. 다음 예시 AWS Code 아티팩트 토큰을 발행하고 하나 빌드 명령으로 업로드합니다.
export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \ --domain my-domain --query authorizationToken --output text)" agentengine build --upload-build-secrets
수명이 긴 자격 자격 증명 의 경우, agentengine secret set(으)로 각 시크릿을 한 번씩 설정하다 플래그 없이 빌드 . 프로비저닝 시크릿에 대해 자세히 학습 클라우드 시크릿 프로비저닝을 참조하세요.
빌드 관리 명령
다음 표에서는 에이전트 빌드를 모니터 하고 관리 데 사용할 수 있는 빌드 관리 명령에 대해 설명합니다.
명령 | 설명 |
|---|---|
| 지정된 빌드 에 대해 |
| 작업 공간의 모든 빌드를 테이블 형식으로 나열합니다. 이 표에는 빌드 ID, 상태, 레이블, 생성 시간이 포함됩니다. |
| 지정된 실행 거나 대기 중인 빌드 취소합니다. 이 명령은 빌드 이미 성공했거나 실패한 경우 오류를 반환합니다. |
| 소스에서 이미지를 다시 빌드하지 않고 성공적인 빌드 이미지를 다른 작업 공간으로 승격합니다. 자세히 학습 빌드 승격을 참조하세요. |
| 지정된 빌드 프로모션의 상태를 반환합니다. 출력에는 대상 빌드 ID 와 승격이 실패한 경우 실패 이유가 포함됩니다. |
팁
명령 플래그
각 빌드 관리 명령은 --workspace-id 및 --project-id 플래그를 허용하여 작업 공간과 프로젝트 지정합니다. 지정하지 않으면 CLI .agentengine/state.json 파일 에서 이러한 값을 읽습니다.
빌드 승격
빌드 승격하면 Atlas Agent Engine은 소스에서 이미지를 다시 빌드하지 않고 테스트된 빌드 이미지를 한 작업 공간에서 다른 작업 공간으로 복사합니다. 승격된 이미지는 소스 이미지와 바이트가 동일하므로 대상 작업 공간에서 실행되는 에이전트 는 소스 작업 공간에서 테스트한 에이전트와 동일합니다.
참고
프로모션은 새 빌드 실행 대신 기존 이미지를 재사용하기 때문에 플랫폼 UI 빌드 세부 정보 페이지에 프로모션된 빌드 에 대한 Build Logs 섹션이 표시되지 않습니다.
기본값 으로 소스 빌드 이미지를 배포할 수 있음을 확인하는 성공적인 배포서버 한 번 이상 있어야 합니다. 이 요구 사항을 우회하려면 --force 플래그를 사용하세요.
빌드 승격하려면 다음 구문을 사용합니다.
agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]
CLI ID 로 소스 빌드 식별하고 현재 조직 내에서 해결합니다. 빌드 다른 조직 의 프로젝트 로 승격할 수 없습니다.
빌드 승격할 때 다음 플래그를 사용할 수 있습니다.
플래그 | 설명 |
|---|---|
| (Monorepo에만 해당) 루트 |
| 대상 플랫폼 작업 공간 ID. |
| 대상 플랫폼 프로젝트 ID. |
|
|
| 성공적인 배포서버 요구 사항을 우회합니다. 이 플래그에는 대상 프로젝트 의 |
| 대화형 확인 메시지를 건너뜁니다. CI 파이프라인 이나 다른 비대화형 환경에서 명령을 실행 때 이 플래그를 사용합니다. 이 옵션이 없으면 대화형 터미널 외부에서는 명령이 실패합니다. |
| 프로모션 결과를 JSON 으로 출력합니다. |
경고
프로모션은 소스 작업 공간에서 런타임 또는 프로젝트 구성을 복사하지 않습니다. 시크릿, Atlas 연결 구성 및 송신 정책은 대상 작업 공간으로 전송되지 않습니다. 승격된 빌드 배포 전에 대상 프로젝트 및 작업 공간에서 이러한 설정을 구성합니다.
승격이 성공하면 대상 작업 공간에 승격된 빌드 배포 . 빌드 배포 방법을 학습 빌드 배포를 참조하세요.
예시
다음 명령은 빌드 상태를 폴링하지 않고 에이전트 이미지를 빌드한 다음 빌드 정보를 나열합니다.
agentengine build --no-wait && agentengine build list
빌드 성공적인 하면 명령 출력은 다음 예시 와 유사합니다.
Initialising build... build_id: <build_id> Creating archive... Uploading archive... Starting build... ✓ Build started (build_id: ...) URL: https://agentengine.mongodb.com/api/v1/workspaces/<workspace_id>/builds/<build_id> BUILD_ID STATUS LABEL CREATED_AT <build_id> running main@abc123def456 2026-04-01T10:30:00Z
다음 단계
에이전트 이미지를 빌드한 후 에이전트 프로덕션에 배포 할 수 있습니다. 에이전트 를 배포 방법을 학습 빌드 배포 가이드 참조하세요.