agent-zero를 Windows, macOS 및 Linux에 설치하는 방법 #

Agent Zero를 설치하는 방법을 알아보려면 비디오를 클릭하세요.

다음 사용자 가이드에서는 프레임워크의 기본 런타임 환경인 Docker를 사용하여 Agent Zero를 설치하고 실행하는 방법을 설명합니다. 개발자와 기여자를 위해 전체 개발 환경을 설정하는 방법도 제공합니다 .

Windows, macOS 및 Linux 설정 가이드 #

1. Docker Desktop 설치:

• Docker Desktop은 Agent Zero에 대한 런타임 환경을 제공하여 플랫폼 전반에 걸쳐 일관된 동작과 보안을 보장합니다.
• 전체 프레임워크는 Docker 컨테이너 내에서 실행되어 격리 및 쉬운 배포를 제공합니다.
• 모든 주요 운영 체제에 사용자 친화적인 GUI 애플리케이션으로 제공

1.1. Docker Desktop 다운로드 페이지로 이동하세요 (여기) . 링크가 작동하지 않으면 웹에서 “docker desktop download”를 검색하세요.

1.2. 운영 체제에 맞는 버전을 다운로드하세요. Windows 사용자의 경우 Intel/AMD 버전이 주요 다운로드 버튼입니다.

메모

Linux 사용자: Docker Desktop 또는 docker-ce(커뮤니티 에디션)를 설치할 수 있습니다. Docker Desktop의 경우, 해당 Linux 배포판의 지침을 여기에서 확인하세요. docker-ce의 경우, 여기의 지침을 따르세요 .

docker-ce를 사용하는 경우 사용자를 그룹에 추가해야 합니다 docker.

sudo usermod -aG docker $USER

로그아웃했다가 다시 로그인한 후 다음을 실행하세요.

docker login

1.3. 기본 설정으로 설치 프로그램을 실행하세요. macOS에서는 애플리케이션을 응용 프로그램 폴더로 끌어다 놓으세요.

1.4. 설치가 완료되면 Docker Desktop을 실행하세요.

메모

macOS 구성: Docker Desktop의 환경 설정(Docker 메뉴) → 설정 → 고급에서 “기본 Docker 소켓 사용 허용(비밀번호 필요)”을 활성화합니다.

2. 에이전트 제로를 실행하세요:

• 참고: Agent Zero는 사이버 보안 작업을 위해 수정된 프롬프트를 갖춘 Kali Linux 기반 해킹 에디션도 제공합니다. 설정은 일반 버전과 동일하며, agent0ai/agent-zero 대신 agent0ai/agent-zero:hacking 이미지를 사용하면 됩니다.

2.1. Agent Zero Docker 이미지를 가져옵니다.

• agent0ai/agent-zeroDocker Desktop에서 검색
• Pull버튼을 클릭하세요
• 몇 분 안에 이미지가 귀하의 컴퓨터에 다운로드됩니다.

팁

또는 터미널에서 다음 명령을 실행하세요.

docker pull agent0ai/agent-zero

2.2. 선택 사항 – 지속성을 위한 데이터 디렉터리를 만듭니다.

주의

Agent Zero 데이터를 유지하는 가장 좋은 방법은 백업 및 복원 기능을 사용하는 것입니다. 전체 /a0디렉터리를 로컬 디렉터리에 매핑하면 Agent Zero를 최신 버전으로 업그레이드할 때 문제가 발생합니다.

• Agent Zero의 데이터를 저장할 디렉토리를 컴퓨터에서 선택하거나 생성하세요.
• 이것은 귀하가 선호하는 어떤 위치든 될 수 있습니다(예: C:/agent-zero-data또는 /home/user/agent-zero-data)
• 개별 하위 폴더를 /a0로컬 디렉토리나 전체 /a0디렉토리에 매핑할 수 있습니다(권장하지 않음).
• 이 디렉토리에는 레거시 루트 폴더 구조와 같이 모든 Agent Zero 파일이 포함됩니다.
  • /agents– 프롬프트와 도구를 갖춘 전문 에이전트
  • /memory– 에이전트의 기억과 학습된 정보
  • /knowledge– 지식 기반
  • /instruments– 기구 및 기능
  • /prompts– 프롬프트 파일
  • /work_dir– 작업 디렉토리
  • .env– 귀하의 API 키
  • /tmp/settings.json– Agent Zero 설정

팁

접근 및 백업이 쉬운 위치를 선택하세요. Agent Zero의 모든 데이터는 이 디렉터리에서 바로 접근할 수 있습니다.

2.3. 컨테이너를 실행합니다.

• Docker Desktop에서 “이미지” 탭으로 돌아갑니다.
• 이미지 Run옆에 있는 버튼을 클릭하세요agent0ai/agent-zero
• “선택적 설정” 메뉴를 엽니다
• 두 번째 “호스트 포트” 필드에서 웹 포트(80)를 원하는 호스트 포트 번호로 설정하거나 0자동 포트 할당을 위해 설정하십시오.

선택적으로 파일 지속성을 위해 로컬 폴더를 매핑할 수 있습니다.

주의

Agent Zero 데이터를 유지하는 가장 좋은 방법은 백업 및 복원 기능을 사용하는 것입니다. 전체 /a0디렉터리를 로컬 디렉터리에 매핑하면 Agent Zero를 최신 버전으로 업그레이드할 때 문제가 발생합니다.

• 선택 사항: 필요한 경우 “볼륨”에서 매핑된 폴더를 구성합니다.
  • 예시 호스트 경로: 선택한 디렉토리(예: C:\agent-zero\memory)
  • 컨테이너 경로 예:/a0/memory
• Run“이미지” 탭에서 버튼을 클릭하세요 .

• 컨테이너가 시작되어 “컨테이너” 탭에 표시됩니다.

팁

또는 터미널에서 다음 명령을 실행하세요.

docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero

• $PORT사용하고자 하는 포트로 바꾸세요 (예: 50080)
• /path/to/your/data선택한 디렉토리 경로로 바꾸세요

2.4. 웹 UI에 접속하세요:

• 프레임워크를 초기화하는 데 몇 초가 걸리며 Docker 로그는 아래 이미지와 같습니다.
• Docker Desktop에서 매핑된 포트를 찾으세요( 로 표시됨 <PORT>:80) 또는 아래 이미지에 표시된 대로 컨테이너 ID 바로 아래에 있는 포트를 클릭하세요.

• http://localhost:<PORT>브라우저에서 열기
• 웹 UI가 열립니다. Agent Zero를 구성할 준비가 되었습니다!

팁

Docker Desktop의 컨테이너 ID 바로 아래에 있는 포트를 클릭하여 웹 UI에 액세스할 수도 있습니다.

메모

컨테이너를 시작하면 선택한 디렉터리에 모든 Agent Zero 파일이 표시됩니다. 컴퓨터에서 직접 이러한 파일에 접근하여 편집할 수 있으며, 변경 사항은 실행 중인 컨테이너에 즉시 반영됩니다.

3. Agent Zero 구성

• Agent Zero를 구성하는 방법에 대한 전체 가이드는 다음 섹션을 참조하세요.

설정 구성 #

Agent Zero는 다양한 기능을 사용자 지정할 수 있는 포괄적인 설정 인터페이스를 제공합니다. 사이드바에서 기어 아이콘이 있는 “설정” 버튼을 클릭하여 설정에 액세스하세요.

에이전트 구성 #

• 프롬프트 하위 디렉터리: 에이전트 동작 사용자 지정을 위한 하위 디렉터리를 선택하세요 /prompts. ‘기본’ 디렉터리에는 표준 프롬프트가 포함되어 있습니다.
• 메모리 하위 디렉토리: 에이전트 메모리 저장을 위한 하위 디렉토리를 선택하여 서로 다른 인스턴스를 분리합니다.
• 지식 하위 디렉토리: 에이전트의 이해를 높이기 위해 사용자 정의 지식 파일의 위치를 지정합니다.

채팅 모델 설정 #

• 제공자: 채팅 모델 제공자를 선택하세요(예: Ollama)
• 모델 이름: 특정 모델을 선택하세요(예: llama3.2)
• 온도: 응답 무작위성 조정(결정적 응답의 경우 0, 더 창의적인 응답의 경우 더 높은 값)
• 컨텍스트 길이: 컨텍스트 창에 대한 최대 토큰 제한을 설정합니다.
• 컨텍스트 창 공간: 컨텍스트 창의 얼마나 많은 부분을 채팅 기록에 할애할지 구성합니다.

실용신안 구성 #

• 공급자 및 모델: 메모리 구성 및 요약과 같은 유틸리티 작업을 위해 더 작고 빠른 모델을 선택하세요.
• 온도: 유틸리티 응답의 결정론을 조정합니다.

임베딩 모델 설정 #

• 제공자: 임베딩 모델 제공자(예: OpenAI)를 선택하세요.
• 모델 이름: 특정 임베딩 모델을 선택하세요(예: text-embedding-3-small)

음성-텍스트 변환 옵션 #

• 모델 크기: 음성 인식 모델 크기를 선택하세요
• 언어 코드: 음성 인식을 위한 기본 언어 설정
• 무음 설정: 음성 입력에 대한 무음 임계값, 지속 시간 및 시간 초과 매개변수를 구성합니다.

API 키 #

• 웹 UI 내에서 다양한 서비스 제공자에 대한 API 키를 직접 구성합니다.
• Save설정을 확인하려면 클릭하세요

입증 #

• UI 로그인: 웹 인터페이스 액세스를 위한 사용자 이름 설정
• UI 비밀번호: 웹 인터페이스 보안을 위한 비밀번호 구성
• 루트 비밀번호: SSH 액세스를 위한 Docker 컨테이너 루트 비밀번호 관리

개발 설정 #

• RFC 매개변수(로컬 인스턴스만 해당): 인스턴스 간 원격 함수 호출에 대한 URL 및 포트 구성
• RFC 비밀번호: 원격 함수 호출에 대한 비밀번호를 구성합니다. 원격 함수 호출과 그 목적에 대해 자세히 알아보려면 여기를 클릭하세요 .

중요한

API 키와 비밀번호를 항상 안전하게 보관하세요.

LLM 선택하기 #

설정 페이지는 Agent Zero를 구동하는 대규모 언어 모델(LLM)을 선택하는 제어 센터입니다. 역할에 따라 다양한 LLM을 선택할 수 있습니다.

LLM 역할	설명
chat_llm	이것은 대화와 응답 생성에 사용되는 기본 LLM입니다.
utility_llm	이 LLM은 메시지 요약, 메모리 관리, 내부 프롬프트 처리와 같은 내부 작업을 처리합니다. 더 작고 저렴한 모델을 사용하면 효율성을 향상시킬 수 있습니다.
embedding_llm	이 LLM은 메모리 검색 및 지식 기반 조회에 사용되는 임베딩을 생성합니다. 이 값을 변경하면 embedding_llmA0의 모든 메모리가 다시 인덱싱됩니다.

변경 방법:

1. 웹 UI에서 설정 페이지를 엽니다.
2. 각 역할(채팅 모델, 유틸리티 모델, 임베딩 모델)에 대한 LLM 공급자를 선택하고 모델 이름을 작성하세요.
3. 변경 사항을 적용하려면 “저장”을 클릭하세요.

중요한 고려 사항 #

Ollama 설치 및 사용(로컬 모델) #

다양한 대규모 언어 모델을 로컬에서 실행할 수 있는 강력한 도구인 Ollama에 관심이 있으시다면, 설치 및 사용 방법은 다음과 같습니다.

첫 번째 단계: 설치 #

Windows의 경우:

공식 웹사이트에서 Ollama를 다운로드하여 컴퓨터에 설치하세요.

Ollama 설치 프로그램 다운로드

macOS에서:

brew install ollama

그렇지 않으면 공식 웹사이트 에서 macOS 설치 프로그램을 선택하세요 .

Linux의 경우:

curl -fsSL https://ollama.com/install.sh | sh

모델 이름 찾기: Ollama 모델 라이브러리를 방문하여 사용 가능한 모델과 해당 이름 목록을 확인하세요. 형식은 일반적으로 provider/model-name(또는 model-name경우에 따라) 다음과 같습니다.

두 번째 단계: 모델 끌어오기 #

Windows, macOS 및 Linux의 경우:

ollama pull <model-name>

1. <model-name>사용할 모델 이름으로 바꾸세요 . 예를 들어 Mistral Large 모델을 가져오려면 명령을 사용합니다 ollama pull mistral-large.
2. CLI 메시지는 시스템에 모델이 다운로드되었음을 확인해야 합니다.

Agent Zero 내에서 모델 선택 #

1. 모델을 다운로드한 후 GUI의 설정 페이지에서 해당 모델을 선택해야 합니다.
2. 채팅 모델, 유틸리티 모델 또는 임베딩 모델 섹션에서 Ollama를 공급자로 선택하세요.
3. llama3.2Ollama가 기대하는 대로 다음 형식으로 모델 코드를 작성하십시오.qwen2.5:7b
4. 일반적으로 ollama API 엔드포인트에 API 기반 URL을 제공합니다.http://host.docker.internal:11434
5. Save설정을 확인하려면 클릭하세요 .

다운로드한 모델 관리 #

일부 모델을 다운로드한 후에는 사용 가능한 모델이 있는지 확인하거나 더 이상 필요하지 않은 모델은 제거하는 것이 좋습니다.

• 다운로드한 모델 나열: 다운로드한 모든 모델 목록을 보려면 다음 명령을 사용하세요.ollama list
• 모델 제거: 다운로드한 모델을 제거해야 하는 경우 ollama rm다음 명령어 뒤에 모델 이름을 입력하면 됩니다.ollama rm <model-name>
• 다양한 모델 조합을 실험하여 필요에 가장 적합한 성능과 비용의 균형을 찾으세요. 예를 들어, 더 빠르고 지연 시간이 짧은 LLM이 도움이 될 수 있으며, 메모리 faiss_gpu대신 를 사용할 수도 있습니다.faiss_cpu

모바일 기기에서 Agent Zero 사용하기 #

Agent Zero의 웹 UI는 Docker 컨테이너를 통해 네트워크의 모든 장치에서 액세스할 수 있습니다.

메모

설정의 외부 서비스 탭에서 Cloudflare Tunnel을 활성화하여 Agent Zero 인스턴스를 인터넷에 노출할 수 있습니다. ⚠️인터넷에서 인스턴스를 보호하려면 설정의 인증 탭에서 사용자 이름과 비밀번호를 설정하는 것을 잊지 마세요.

1. Docker 컨테이너는 모든 네트워크 인터페이스에 웹 UI를 자동으로 노출합니다.
2. Docker Desktop에서 매핑된 포트를 찾으세요.
   • 컨테이너 이름(일반적으로 형식 <PORT>:80) 아래에서 확인하세요.
   • 예를 들어, 을 보면 32771:80포트는 다음과 같습니다.32771
3. 다음을 사용하여 모든 기기에서 웹 UI에 액세스하세요.
   • 로컬 접속:http://localhost:<PORT>
   • 네트워크 접속:http://<YOUR_COMPUTER_IP>:<PORT>

팁

• 컴퓨터의 IP 주소는 일반적으로 192.168.x.x다음 형식입니다.10.0.x.x
• ipconfig(Windows) 또는 ifconfig(Linux/Mac)을 실행하여 외부 IP 주소를 찾을 수 있습니다.
• 포트는 사용자가 지정하지 않는 한 Docker에 의해 자동으로 할당됩니다.

메모

run_ui.pyDocker를 사용하는 대신 시스템에서 Agent Zero를 직접 실행하는 경우(레거시 방식), . 를 사용하여 모든 인터페이스에서 실행되도록 호스트를 수동으로 구성해야 합니다 host="0.0.0.0".

시스템에서 Agent Zero를 직접 실행해야 하는 개발자나 사용자의 경우 전체 바이너리 설치에 대한 심층 가이드를 참조하세요 .

Agent Zero를 업데이트하는 방법 #

메모

Agent Zero v0.9부터 백업 및 복원 기능이 추가되어 파일을 수동으로 백업할 필요가 없습니다. 설정의 백업 및 복원 탭에서 백업 과정을 안내합니다.

1. 이전 버전의 Agent Zero를 사용하시는 경우:

• 귀하의 데이터는 Agent Zero 폴더 내의 다양한 디렉토리와 파일에 안전하게 저장됩니다.
• 새로운 Docker 런타임 버전으로 업데이트하려면 다음 파일과 디렉토리를 백업하는 것이 좋습니다.
  • /memory– 에이전트의 기억
  • /knowledge– 사용자 정의 지식 기반(사용자 정의 지식 파일을 가져온 경우)
  • /instruments– 사용자 정의 악기 및 기능(사용자 정의 악기 및 기능을 만든 경우)
  • /tmp/settings.json– Agent Zero 설정
  • /tmp/chats/– 채팅 기록
• 이러한 파일과 디렉토리를 저장한 후에는 위의 설치 가이드에 있는 Docker 런타임 설치 지침 에 따라 진행할 수 있습니다 .
• 데이터를 저장한 폴더로 가서 설치 과정에서 설정한 새 Agent Zero 폴더에 복사합니다.
• Agent Zero는 저장된 데이터를 자동으로 감지하여 메모리, 지식, 도구, 프롬프트 및 설정 전반에 활용합니다.

중요한

설정을 불러오는 데 문제가 있는 경우, 파일을 삭제 /tmp/settings.json하고 Agent Zero에서 새 설정을 생성하도록 해보세요. 채팅도 마찬가지입니다 /tmp/chats/. 새 버전과 호환되지 않을 수 있습니다.

2. 업데이트 프로세스(Docker Desktop)

• Docker Desktop으로 이동하여 “컨테이너” 탭에서 컨테이너를 중지합니다.
• 마우스 오른쪽 버튼을 클릭하고 “제거”를 선택하여 컨테이너를 제거하세요.
• “이미지” 탭으로 가서 agent0ai/agent-zero이미지를 제거하거나 세 개의 점을 클릭하여 차이점을 끌어내고 Docker 이미지를 업데이트합니다.

• 제거를 선택한 경우 새 이미지를 검색하여 가져옵니다.
• 이전 컨테이너와 동일한 볼륨 설정으로 새 컨테이너를 실행합니다.

중요한

데이터를 보존하려면 새 컨테이너를 실행할 때 동일한 볼륨 마운트 경로를 사용해야 합니다. 정확한 경로는 Agent Zero 데이터 디렉터리(시스템에서 선택한 디렉터리)를 저장한 위치에 따라 달라집니다.

팁

또는 터미널에서 다음 명령을 실행하세요.

# Stop the current container
docker stop agent-zero

# Remove the container (data is safe in the folder)
docker rm agent-zero

# Remove the old image
docker rmi agent0ai/agent-zero

# Pull the latest image
docker pull agent0ai/agent-zero

# Run new container with the same volume mount
docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero

결론 #

사용 중인 운영 체제에 맞는 지침을 따르면 Agent Zero가 성공적으로 설치 및 실행될 것입니다. 이제 프레임워크의 기능을 살펴보고 나만의 지능형 에이전트를 만들어 보세요.