개요
이 가이드 에서는 단일 리포지토리 에서 여러 에이전트를 관리 위해 단일 리포지토리를 설정하다 하는 방법을 학습 수 있습니다. 단일 리포지토리는 각 에이전트의 이름과 하위 디렉토리 경로를 나열하는 리포지토리 루트의 agent.yaml 파일 사용합니다. 루트 agent.yaml에 entrypoint 키 대신 agents 키가 포함된 경우 CLI 모노리포 형식을 자동으로 감지합니다.
디렉토리 구조
단일 리포지토리에는 각 에이전트의 하위 디렉토리에 루트 agent.yaml와 단일 에이전트 agent.yaml가 필요합니다. 다음 예시 두 개의 에이전트를 포함하는 단일 리포지토리의 파일 구조를 보여줍니다.
my-repo/ ├── agent.yaml # Monorepo root file ├── .env # Shared secrets for the local dev stack ├── pyproject.toml # Shared Python dependencies (optional) ├── agents/ │ ├── chat/ │ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ │ ├── pyproject.toml │ │ ├── .env # Per-agent secrets │ │ └── src/ │ └── search/ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ ├── pyproject.toml │ ├── .env # Per-agent secrets │ └── src/ └── shared/ # Shared libraries, included in all builds
Monorepo 구성
다음 단계는 필요한 모노리포 파일을 구성하고 모노리포를 초기화하는 방법을 보여줍니다.
루트 agent.yaml 파일 구성합니다.
리포지토리 루트에 agent.yaml 파일 생성합니다. agents 목록을 사용하여 각 에이전트의 이름과 경로를 선언합니다. 루트 파일 에 entrypoint 필드 포함하지 마세요.
agents 목록의 각 항목에는 다음 필드가 필요합니다.
필드 | 필수 사항 | 설명 |
|---|---|---|
| 네 | 에이전트 식별자입니다. 이 필드 하이픈이 포함된 소문자 영숫자 값으로 설정합니다. 선행 또는 후행 하이픈을 사용하지 말고 이름이 단일 리포지토리 내에서 고유한지 확인합니다. |
| 네 | 리포지토리 루트에서 에이전트 디렉토리 까지의 상대 경로입니다. 경로는 절대 경로이거나 |
다음 샘플 agent.yaml 파일 chat 및 search라는 두 에이전트로 단일 리포지토리를 구성합니다.
agents: - name: chat path: agents/chat - name: search path: agents/search
각 에이전트의 agent.yaml 파일 구성합니다.
각 에이전트 하위 디렉토리에서 단일 에이전트 형식을 사용하는 agent.yaml 파일 생성합니다. 파일 에이전트의 애플리케이션 객체 가리키는 entrypoint 필드 와 에이전트 도구가 실행 항목과 액세스 할 수 있는 시크릿을 정의하는 sandboxes 필드 포함되어야 합니다. 사용 가능한 모든 필드를 보려면 프로젝트 생성 가이드 에서 에이전트 .yaml 필드 목록을 참조하세요.
다음 샘플 agent.yaml 파일 chat 에이전트 구성합니다.
entrypoint: chat_agent.graph:app name: chat sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
다음 샘플 agent.yaml 파일 search 에이전트 구성합니다.
entrypoint: search_agent.graph:app name: search sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
agent 샌드박스는 중단 도구와 같이 에이전트 에서 실행 되어야 하는 도구를 위한 것입니다. tool 샌드박스는 에이전트 와 별도로 실행 도구를 위한 것입니다. tools 필드 아래에 각 샌드박스의 도구를 나열합니다. 각 샌드박스의 secrets 필드 에서 시크릿 액세스 구성합니다. 샌드박스가 선택한 시크릿만 수신해야 하는 경우 ["*"]를 특정 시크릿 이름 목록으로 대체합니다.
중요
각 하위 디렉토리에는 에이전트의 Python 종속성을 선언하는 pyproject.toml 파일 도 포함되어야 합니다. 파일 [project].name 키를 설정하다 하고 requires 및 build-backend 키를 설정하는 [build-system] 테이블을 포함해야 합니다. 이러한 요구 사항을 충족하는 파일 생성하려면 에이전트 하위 디렉토리에서 uv init --package를 실행 .
.env 파일을 생성합니다.
단일 리포지토리는 로컬 개발자 스택 모든 에이전트에서 공유하는 시크릿에 대한 루트 .env 파일과 해당 에이전트의 자체 시크릿을 위한 각 에이전트 하위 디렉토리에 있는 에이전트별 .env, 두 가지 유형의 .env 파일을 사용합니다. 로컬 환경을 시작하기 전에 수동으로 생성하세요.
다음 예시 와 같이 리포지토리 루트에서 로컬 개발 중에 오케스트레이션 엔진 과 모든 에이전트 사용하는 시크릿이 포함된 .env 파일 생성합니다.
MONGODB_URI=<your-mongodb-connection-string> <PROVIDER>_API_KEY=<your-api-key>
각 에이전트 하위 디렉토리에서 해당 에이전트 만 사용하는 시크릿(예: 에이전트별 API 키)에 대한 .env 파일 생성합니다.
중요
시크릿을 버전 관리에 커밋 하지 마세요.
단일 에이전트에서 Monorepo로 마이그레이션
기존 단일 에이전트 리포지토리 모노 리포지토리로 변환하려면 에이전트 파일을 하위 디렉토리로 이동하고 프로젝트 다시 초기화합니다.
다음 단계는 단일 리포지토리로 마이그레이션 방법을 보여줍니다.
에이전트 하위 디렉토리를 생성하고 파일을 이동합니다.
다음 명령을 실행하여 에이전트 의 하위 디렉토리를 만들고 다음 파일을 하위 디렉토리로 이동합니다.
mkdir -p agents/<agent-name> mv agent.yaml pyproject.toml .env src/ agents/<agent-name>/
<agent-name> 자리 표시자를 에이전트 이름으로 바꿉니다.
참고
디렉토리 구조
앞의 예시 에서는 agents/ 디렉토리 에 하위 디렉토리를 생성합니다. 다른 디렉토리 구조를 사용할 수 있지만 루트 agent.yaml의 path 값은 해당 상대 경로를 지정해야 합니다.
.agentengine/ 디렉토리 에이전트 하위 디렉토리로 이동합니다.
agentengine init를 실행 하면 CLI .agentengine/state.json 파일 에 작업 공간 등록 상태 포함된 숨겨진 .agentengine/ 디렉토리 생성합니다. 단일 리포지토리에서 각 에이전트 에는 고유한 .agentengine/ 디렉토리 필요합니다.
다음 명령을 실행하여 기존 디렉토리 에이전트 하위 디렉토리로 이동하면 에이전트의 작업 공간 등록이 유지됩니다.
mv .agentengine/ agents/<agent-name>/.agentengine/
중요
.agentengine/ 디렉토리 이동하지 않는 경우 agentengine init를 실행 에이전트 에 새 작업 공간이 등록되고 이전 작업 공간 등록이 고아가 됩니다.
루트 agent.yaml 파일 생성합니다.
이전 Monorepo 구성 섹션에 설명된 대로 리포지토리 루트에서 agents 키를 사용하여 에이전트 나열하는 새 agent.yaml를 생성합니다.
다음 단계
모노 리포지토리를 설정한 후 에이전트를 빌드 하고 배포 할 수 있습니다. 방법을 학습 다음 가이드를 참조하세요.