Agents를 로컬에서 실행하기

이 페이지를 사용하여 추출한 Agents 프로젝트를 컴퓨터에서 실행할 수 있습니다. ReAct 루프, 함수 호출 루프, 최종 인터페이스는 모두 동일한 Vite 설정을 사용하지만 결과를 다른 위치에 표시합니다. 마일스톤을 시작하기 전에 OpenAI 키 조회와 레거시 모델 ID를 업데이트합니다.

먼저 필요한 것

지원되는 LTS 버전의 Node.js를 설치합니다. Node 24를 권장하며 npm이 포함되어 있습니다. 내보내기는 Vite 프로젝트이므로 Node와 npm만으로 필요한 모든 도구를 갖추게 됩니다.

또한 결제 및 모델 접근이 활성화된 OpenAI API 키가 필요합니다. 모델 접근은 OpenAI 대시보드에서 프로젝트별로 설정됩니다. 키가 속한 프로젝트는 아래에서 구성할 모델을 허용해야 합니다. 키 자체는 이후 단계에서 .env 파일에 들어갑니다.

Juno먼저 필요한 것 Node.js의 LTS 버전을 설치합니다. npm이 함께 제공됩니다. 또한 유료 모델 요청을 할 수 있는 계정의 OpenAI API 키가 필요합니다. 시작하기 전에 둘 다 준비해 두면 설정 도중에 멈춰서 찾을 필요가 없습니다. 저도 예전에 자주 그렇게 했거든요!

Juno먼저 필요한 것 내보내기는 Vite 프로젝트이므로 Node LTS와 npm이 전체 도구입니다. OpenAI 키는 몇 단계 후 .env에 들어가고, 모델 접근은 OpenAI 대시보드에서 키의 프로젝트에 있는 허용 모델 목록을 의미합니다. 지금 그 목록을 확인하면 나중에 가장 혼동하기 쉬운 오류를 피할 수 있습니다.

Juno먼저 필요한 것 Vite는 작동하지 않는 키로도 이 프로젝트를 시작할 수 있으므로, 잘못된 키가 이 페이지에서 가장 조용한 실패입니다. 에이전트 루프가 첫 번째 모델 요청을 하고 인증 또는 할당량 오류를 받을 때까지 아무도 문제를 보고하지 않습니다. 코드를 탓하기 전에 결제와 모델 접근을 확인합니다. 저는 코드를 먼저 탓해서 한 번 아침을 통째로 잃었습니다.

프로젝트 열고 설치하기

package.json이 포함된 추출된 폴더에서 터미널을 열고 패키지를 설치합니다:

$ cd path-to-your-downloaded-project
$ npm install

Juno프로젝트 열고 설치하기package.json이 포함된 추출된 폴더를 열고 거기서 npm install을 실행합니다. 이 페이지의 이후 모든 명령은 같은 폴더에서 실행됩니다. 한 터미널을 그 폴더에서 계속 열어 두면 어디에 있는지 놓칠 일이 없습니다. 처음 한 달에는 저도 자주 놓쳤거든요.

Juno프로젝트 열고 설치하기 세 마일스톤 모두 npm과 Vite 설정을 공유하므로, 어느 것을 추출했든 이 설치 단계는 동일합니다. package.json 옆에 설치한 후 다음 섹션에서 설명하는 두 가지 코드 변경을 합니다. 모든 명령은 같은 폴더에서 실행됩니다.

Juno프로젝트 열고 설치하기 이 내보내기는 정확한 버전을 고정하는 package-lock.json인 lockfile 없이 제공되므로, npm install이 OpenAI SDK와 Vite를 컴퓨터에서 새로 해결합니다. 다양한 해결된 버전이 가능하지만 여기서는 드문 원인입니다. 나중에 뭔가 깨지면 패키지 버전 변경을 시작하기 전에 소스 편집을 확인합니다.

키와 모델 업데이트하기

index.js에서 다음을 변경합니다:

apiKey: process.env.OPENAI_API_KEY,

다음으로:

apiKey: import.meta.env.VITE_OPENAI_API_KEY,

Vite는 import.meta.env를 통해 환경 값을 읽습니다. 같은 수정이 Running Embeddings and Vector Databases locally에도 나타나며, 유사한 과정 내보내기를 조정합니다.

과정 스냅샷은 gpt-3.5-turbo, gpt-3.5-turbo-1106, gpt-4-1106-preview 같은 레거시 모델 ID를 사용합니다. 이 과정 예제의 경우, 추출된 index.js의 모델 값을 gpt-4o-mini로 바꿉니다:

model: "gpt-4o-mini",

package.json 옆에 .env를 만듭니다:

VITE_OPENAI_API_KEY=your-openai-api-key

같은 폴더에 .gitignore를 만듭니다:

.env
node_modules/

.gitignore는 이 폴더에서 만드는 저장소에 키가 들어가지 않게 합니다. ignoring files and good habits에서 왜 그것이 중요한지 설명합니다.

이 학습 설정은 키를 노출합니다

OpenAI SDK는 의도적으로 브라우저에서 실행되고 있으며, Vite는 키를 프론트엔드 번들에 배치합니다. 임시의 제한된 키만 사용합니다. 이 버전을 배포하거나 공유하지 마십시오. 프로덕션 에이전트에는 백엔드가 필요합니다.

Juno키와 모델 업데이트하기index.js에서 기존 키 조회와 모델 이름을 바꾸고, 임시 키를 .env에 넣고, 그 파일을 Git에서 제외합니다. 이 학습 버전은 의도적으로 키를 브라우저에 표시하므로, 이 프로젝트를 마친 순간 취소할 수 있는 키를 사용합니다. 다른 무엇이 의존하는 키는 사용하지 마십시오.

Juno키와 모델 업데이트하기 Vite는 VITE_로 시작하는 변수만 노출하므로, 소스의 이름과 .env의 이름이 정확히 일치해야 합니다. 다양한 마일스톤이 다양한 스냅샷을 포함하므로 전체 다운로드에서 레거시 모델 ID도 검색합니다. 하나의 ID를 놓치면 한 마일스톤은 작동하고 다른 하나는 실패합니다.

Juno키와 모델 업데이트하기 프로덕션 해결책은 아키텍처입니다: 백엔드에서 OpenAI 클라이언트를 만들고 브라우저가 그 백엔드를 호출하도록 하면 키가 절대 서버를 떠나지 않습니다. 여기서 Vite 대체는 학습 모드에 속하며, 배포할 패턴이 아닙니다. 시작 후에 백엔드를 추가하는 것이 처음부터 만드는 것보다 비용이 많이 듭니다. 저는 두 가지 순서로 모두 해봤습니다.

프로젝트 실행하기

$ npm start

Vite가 인쇄한 정확한 Local URL을 엽니다. 콘솔 전용 마일스톤의 경우 브라우저의 개발자 도구를 열고 Console을 선택합니다. ReAct와 함수 루프는 진행 상황과 응답을 거기에 인쇄합니다. UI 마일스톤에서는 메시지를 보내고 페이지에서 응답을 찾습니다. Ctrl+C로 Vite를 중지합니다.

Juno프로젝트 실행하기npm start를 실행하고 Vite가 인쇄한 정확한 Local URL을 엽니다. 초기 마일스톤의 경우 출력이 브라우저의 Console에 나타나므로, 빈 것처럼 보이는 페이지도 올바르게 실행 중일 수 있습니다. 완료하면 Ctrl+C를 눌러 중지합니다.

Juno프로젝트 실행하기 Vite가 포트를 선택하고 정확한 주소를 인쇄하므로 기억된 URL이 아니라 인쇄된 것을 사용합니다. 콘솔 전용 마일스톤에서 빈 페이지는 예상할 수 있는 것입니다. 시작 실패로 취급하기 전에 개발자 Console에서 루프 출력을 확인합니다. UI 마일스톤만 페이지 자체에서 답변합니다.

Juno프로젝트 실행하기 Vite가 시작되는 것은 편집된 프로젝트가 컴파일된다는 것을 증명할 뿐입니다. OpenAI는 아직 접근되지 않았습니다. DevTools의 루프 출력이든 최종 인터페이스를 통한 메시지든 하나의 실제 상호작용을 실행해야 설정이 완료되었다고 결정합니다. 컴파일되는 프로젝트가 작동하는 프로젝트는 아니며, 저는 몇 년 전에 그 결론을 받아들이는 것을 멈췄습니다.

문제 해결

process is not defined: index.js에서 남아 있는 process.env.OPENAI_API_KEY를 검색하고 위의 Vite 형식으로 바꿉니다.

레거시 모델을 사용할 수 없습니다: 모든 model 필드가 OpenAI 프로젝트에서 사용 가능한 현재 모델을 사용하는지 확인합니다. 다운로드된 마일스톤은 다양한 레거시 ID를 포함할 수 있습니다.

페이지가 비어 있습니다: 초기 마일스톤은 페이지가 아닌 개발자 콘솔에서 진행 상황을 보고합니다. 시각적 채팅 인터페이스를 원하면 최종 UI 레슨을 사용합니다.

인증 또는 할당량 오류: .env가 package.json 옆에 있는지 확인하고, Vite를 다시 시작하고, OpenAI 계정에서 결제 및 키 접근을 확인합니다.

Juno문제 해결 각 증상을 해결책과 일치시킵니다: process is not defined는 키 조회가 여전히 변경이 필요하다는 뜻이고, 빈 페이지는 보통 출력이 Console에 있다는 뜻이고, 인증 오류는 키나 계정을 가리킵니다. 각각 단일 수정입니다. 침착하게, 하나씩 진행하십시오.

Juno문제 해결 순서대로 확인합니다: 소스가 Vite 변수를 읽고, .env가 일치하는 이름을 사용하고, 모든 모델 ID가 현재이고, 해당 마일스톤이 실제로 출력하는 위치를 보고 있습니다. 그 순서는 요청이 만들어지는 순서를 따릅니다. 따라서 실패하는 첫 단계가 원인입니다. 그것을 수정하고 다른 것을 변경하기 전에 다시 실행합니다.

Juno문제 해결 에이전트가 침묵할 때는 네 가지 가능한 원인이 있습니다: 키가 절대 번들에 도달하지 않았거나, 모델 ID가 더 이상 존재하지 않거나, OpenAI가 계정을 거부했거나, UI가 반환된 메시지를 폐기했습니다. 그 순서대로 확인합니다. 목록 초반의 실패가 그 이후의 것과 동일한 증상을 생성하기 때문입니다. 이를 잘못된 순서로 확인하면 한 번 5분짜리 수정이 하루 종일 걸렸습니다.