로컬에서 에이전트 실행 및 테스트

메모리 활성화

agent.yaml 파일 에 features.memory: true을 설정하다 경우, 로컬 환경을 시작하기 전에 .env 파일 에 다음 변수를 추가합니다:

• VOYAGE_API_KEY: 메모리 임베딩을 생성하는 데 필요합니다.

• MONGOMEM_DB_NAME: 선택 사항입니다. 메모리 서버 기록하는 MongoDB database 이름입니다. 기본값은 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

핫 리로드 모드(권장)

핫 리로드 모드 단일 앱 컨테이너 내에서 모든 에이전트 서비스를 실행하고 소스 코드 직접 마운트합니다. 파일 편집하면watchfiles가 변경 사항을 감지하고 전체를 다시 빌드할 필요 없이 영향을 받는 서비스를 자동으로 다시 로드합니다.

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 파일 대신 lockfile에서 종속성을 해결합니다.

새 종속성을 설치하려면 다음 명령을 실행 uv.lock 파일 삭제 하고 스택 다시 시작합니다.

rm uv.lock
agentengine dev stop
agentengine dev up

또는 스택 다시 시작하기 전에 다음 명령을 실행 잠금 파일을 업데이트 할 수 있습니다.

uv lock
agentengine dev stop
agentengine dev up

비공개 아티팩트 리포지토리 사용

에이전트 가 비공개 아티팩트 리포지토리(예: 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 Code 아티팩트 인덱스 의 경우 활성 AWS 프로필 또는 SSO 세션에서 생성된 토큰입니다.

선언된 리포지토리 에 대한 자격 증명이 확인되지 않으면 CLI 실패하고 확인할 리포지토리 와 소스의 이름을 지정합니다.

자동 구성을 건너뛰고 UV_INDEX_* 변수를 직접 관리 하려면 다음 명령을 실행 .

agentengine dev up --no-artifact-auth

artifact_repositories 스키마 에 대해 학습 에이전트 YAML 스키마를 참조하세요. cloud 빌드에서 비공개 아티팩트 리포지토리가 작동하는 방식을 학습 보려면 비공개 아티팩트 리포지토리를 참조하세요.

서비스 중지

컨테이너를 제거하지 않고 로컬 환경을 일시 중지하려면 다음 명령을 실행 .

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의 개발자 자격 증명 캐시 에 로그인 자격 증명 쓰기 (write) , 생성된 agentengine dev up 스택은 해당 디렉토리 자동으로 마운트합니다.

캐시 각 프로젝트 와 각 MCP 엔드포인트에 대해 별도입니다. 한 프로젝트 에서 로그인해도 다른 프로젝트 에 로그 되지 않으므로 프로젝트 당 한 번씩 agentengine dev mcp auth login 명령을 실행 해야 합니다. 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]