프로젝트 생성

명령 구문

다음 명령을 사용하여 새 프로젝트 스캐폴딩합니다.

agentengine create [--template <template-id>] [--name <display-name>] [--dir <path>] [--llm <provider>] [--llm-base-url <url>] [--llm-model <model>] [--llm-auth-header <header>] [--memory] [--yes]

지정한 플래그에 따라 CLI 프로젝트 구성하라는 메시지를 표시합니다.

이 명령은 project-config.yaml 파일 포함된 프로젝트 디렉토리 생성하고, <project-directory>/agents/<slug> 하위 디렉토리에 에이전트의 작업 공간 디렉토리 스캐폴딩합니다. <slug> 값은 --name 값의 소문자에 하이픈으로 연결된 버전입니다. 작업 공간 디렉토리 agent.yaml, .env 및 이후 섹션에서 설명하는 기타 에이전트별 파일이 들어 있습니다.

명령 플래그

표시 이름 제한

CLI 는 표시 이름을 생성된 소스 파일에 복사합니다. 이름에는 다음 문자를 포함할 수 없습니다.

• 큰따옴표(")

• 백슬래시(\)

• 백틱

• 제어, 줄 바꿈 또는 텍스트 방향 문자

대화형 CLI 사용할 때 잘못된 이름을 입력하면 CLI 오류가 표시되고 메시지가 다시 표시됩니다. --name 플래그에 잘못된 이름을 전달하면 명령이 실패하고 허용되지 않는 문자 또는 문자 카테고리의 이름을 지정하는 오류가 발생합니다.

지원되는 템플릿

다음 표에서는 agentengine create 명령에 전달할 수 있는 스타터 템플릿에 대해 설명합니다.

로컬 환경 기본값

제공자 카탈로그에서 LLM 연결을 선택하면 agentengine create에서 필요한 연결 세부 정보(예: API 키)를 입력하라는 메시지를 표시합니다. 셸 환경에 LLM_API_KEY이 설정하다 경우 명령은 이를 기본값 으로 제공합니다. 값을 확인하면 명령은 생성된 .env 파일 에 LLM_API_KEY로 값을 씁니다. 이 값을 수동으로 구성할 필요는 없습니다.

메모리가 활성화되면 agentengine create는 로컬 환경에서 VOYAGE_API_KEY를 감지하여 기본값 으로 제공합니다. 값을 확인하면 생성된 .env에 값이 기록됩니다.

--yes 플래그와 함께 agentengine create를 실행 명령은 감지된 환경 값을 묻는 메시지를 표시하지 않습니다. custom를 제외한 모든 제공자 카탈로그 옵션의 경우, 명령을 실행 전에 환경에서 LLM_API_KEY를 설정하다 해야 합니다. --memory --yes도 전달하는 경우, 명령을 실행 전에 환경에서 VOYAGE_API_KEY를 설정하다 해야 하며, 그렇지 않으면 명령이 실패합니다.

chatbot-client 템플릿은 .env 파일 대신 .env.local 파일 생성합니다. 앱 실행 전에 .env.local 파일 다음 값으로 수동으로 채워야 합니다.

• 배포된 에이전트의 API URL

• 프로젝트 ID

• 작업 공간 ID

• 서비스 계정 액세스 토큰

스캐폴딩 에이전트 사용자 지정

agentengine create가 완료되면 에이전트의 작업 공간 디렉토리 <project-directory>/agents/<slug>로 이동하여 생성된 파일을 검토 .

생성된 모든 에이전트에는 .agents/skills/atlas-agent-engine(Codex, Copilot 및 기타 에이전트의 경우) 또는 .claude/skills/atlas-agent-engine(Claude Code의 경우)의 atlas-agent-engine 스킬 포함됩니다.

에이전트 스타터 템플릿을 사용하는 경우, 생성된 에이전트 소스 및 .env 파일 검토 LLM 연결이 요구 사항을 충족하는지 확인합니다. LLM 클라이언트, 모델, 엔드포인트 및 인증 동작은 생성된 에이전트 소스 코드 에 구성됩니다.

LLM 연결을 구성하는 카탈로그 옵션의 경우, 생성된 .env 파일 LLM_API_KEY(으)로 공유 자격 증명이 포함되어 있습니다. Manual setup를 선택하는 경우, 에이전트 코드에서 LLM 연결을 구성하고 코드에 필요한 시크릿을 .env 파일 에 추가합니다. 자세히 학습 코드에서 LLM 게이트웨이 설정을 참조하세요.

chatbot-client 템플릿을 사용할 때 .env.local 파일 검토 배포된 에이전트의 API URL, 프로젝트 ID, 작업 공간 ID 및 서비스 계정 액세스 토큰을 올바르게 설정하다 했는지 확인합니다. 챗봇 클라이언트 앱 에는 agent.yaml 파일 없습니다.

스타터 템플릿에서 LLM 게이트웨이 설정

agentengine create 명령을 실행 하면 다음 예시 와 유사하게 LLM 연결을 선택하라는 메시지가 표시됩니다.

Which LLM connection do you want to use?
  1) OpenAI
  2) Anthropic
  3) Google Gemini
  4) OpenRouter
  5) OpenAI-compatible - AWS Bedrock, Azure Foundry
  6) Anthropic-compatible - AWS Bedrock, Azure Foundry
  7) Manual setup - implement the LLM client in code

이 카탈로그에서 제공자 선택하면 agentengine create 명령은 다음을 포함하여 연결에 필요한 세부 정보를 입력하라는 메시지를 표시합니다.

• 기본 URL

• 모델 또는 배포서버 이름

• API 키

• 호스팅하다 인식되지 않는 경우 연결을 위한 인증 헤더입니다.

이 명령은 선택한 LLM 클라이언트 생성된 에이전트 소스에 쓰고 생성된 .env 파일 에 LLM_API_KEY로 공유 자격 증명을 저장합니다.

이 명령은 에이전트 및 도구가 외부 호스트에 액세스 방법을 선택하라는 메시지도 표시합니다.

• 권장 network.egress 구성을 적용합니다. Manual setup (custom)를 선택한 경우와 같이 사용 가능한 게이트웨이 호스팅하다 없는 경우, 이 옵션은 나중에 LLM 송신을 구성하도록 지시합니다.

• 모든 아웃바운드 액세스 허용합니다.

LLM 연결이 나열된 옵션 중 하나가 아닌 경우 Manual setup를 선택하고 코드에서 게이트웨이를 설정하다 . 이 옵션은 에이전트 코드에서 연결을 구성할 수 있도록 모델 빌더 스텁을 생성합니다.

코드에서 LLM 게이트웨이 설정

LLM을 에이전트 에 연결하려면 프레임워크별 모델을 생성하고 결과 모델 인스턴스 에이전트의 진입점에서 app.llm(...) 메서드로 전달합니다. 모델 구축 코드를 에이전트 코드의 모든 파일 에 넣을 수 있지만 스타터 템플릿은 스텁을 언어별 파일 에 배치합니다. 스타터 템플릿을 사용하지 않는 경우, app.llm(...)가 지원되는 모델 객체 수신하는 한 다른 곳에서 모델을 정의할 수 있습니다.

다음 표에서는 다양한 런타임에 걸쳐 코드에서 LLM 게이트웨이를 설정하기 위한 규칙을 설명합니다.

생성자는 엔드포인트, 인증 헤더 및 모델 이름을 설정하는 것입니다. 예시 들어, LangGraph Python insurance-agent 템플릿은 src/<module>/llm.py에서 build_llm()을 정의하고 LangChain BaseChatModel을 반환합니다. 에이전트 진입점은 build_llm()를 가져오고 반환된 모델을 app.llm(...)에 전달합니다.

에이전트 가 게이트웨이 호스트에 연결할 수 있도록 게이트웨이 호스팅하다 허용합니다. 사용자 지정 게이트웨이 호스팅하다 및 포트를 agent.yaml 파일 의 network.egress 차단 에 추가합니다. 예시 들어 gateway.example.com:443를 도구 샌드박스의 기존 송신 허용 목록에 추가하려면 다음 명령을 실행 .

agentengine agent egress add --component tool gateway.example.com:443

에이전트 의 네트워크 이그레스 구성에 대해 자세히 학습 네트워크 이그레스 시작하기 가이드 참조하세요.

명령 구문

에이전트 작업 공간 디렉토리 에서 다음 명령을 실행 에이전트 를 등록하고 로컬 파일을 생성합니다.

agentengine init [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>]

이 명령은 대화형으로 조직 및 프로젝트 선택하거나 생성하고, 로컬 개발 파일을 생성하고, 에이전트 를 Atlas Agent Engine에 작업 공간으로 등록합니다.

명령 플래그

인터랙티브 플로우

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

1. "Create a new organization..." 옵션을 포함하여 번호가 매겨진 메뉴와 함께 조직을 나열합니다. 조직이 없는 경우 조직을 만들려면 이름을 입력하라는 메시지가 CLI 에 표시됩니다.

2. 조직 선택하면 "Create a new project..." 옵션을 포함하여 번호가 매겨진 메뉴와 함께 프로젝트를 나열합니다. 프로젝트가 없는 경우 CLI 는 프로젝트를 생성하기 위해 이름을 입력하라는 메시지를 표시합니다.

3. 선택한 프로젝트 로컬 인증 상태 의 활성 project_id 로 저장합니다.

4. 에이전트 디렉토리 에 다음과 같은 로컬 개발 파일을 생성합니다.

   • docker-compose.yml

   • .agentengine/Dockerfile

   • .agentengine/entrypoint.py

   • .dockerignore

   • .gitignore

5. 에이전트 를 플랫폼에 작업 공간으로 등록하고 workspace_id, org_id 및 project_id가 지정된 .agentengine/state.json 파일 생성합니다.

상담원 스타터 템플릿

TypeScript 템플릿을 사용하는 경우 로컬에서 에이전트 시작하기 전에 Node.js 종속성을 설치합니다.

pnpm install

스캐폴딩된 에이전트 검토한 후 agentengine dev up를 실행 에이전트 를 로컬에서 시작합니다.

agentengine dev up

챗봇 클라이언트 템플릿

.env.local 파일 에 필요한 값을 설정한 후 종속성을 설치하고 개발 서버 시작합니다.

pnpm install
pnpm run dev

브라우저에서 http://localhost:3000를 열어 채팅 UI 사용합니다.