huanyingtianhe/agents-chat

ACP (Agent Client Protocol) 에이전트를 위한 독립형 멀티 에이전트 채팅 UI입니다. GitHub Copilot CLI, Claude Code 및 모든 ACP 준수 에이전트와 같은 ACP 호환 CLI 도구와 직접 통신합니다.

Node.js >= 20
npm >= 10

최소 하나 이상의 ACP 호환 에이전트가 설치되어 있어야 합니다 (GitHub Copilot CLI, Claude Code 등)

npm install
npm run dev # https://localhost:3010 에서 시작됩니다

https://localhost:3010 을 여세요.

참고: npm run dev는 --experimental-https를 통해 HTTPS를 활성화합니다. 처음 로드할 때 자체 서명된 인증서(self-signed cert)를 수락하세요.

지속적인 배포(persistent deployment)를 위해서는 아래의 플랫폼별 스크립트 중 하나를 사용하세요. 두 스크립트 모두 빌드 + 재시작 + 상태 확인(health check)을 하나의 명령어로 처리합니다.

Windows 머신에서 지속적인 배포를 하려면 scripts\deploy.ps1을 사용하세요. 이 스크립트는 로그인/부팅 시 앱을 자동으로 시작하는 예약된 작업(Scheduled Task)을 관리합니다.

# 배포 (최신 코드를 가져오고, 서비스를 재시작하며, 준비될 때까지 대기합니다)
.\scripts\deploy.ps1
# git pull 없이 배포
...

배포 스크립트 기능:

git에서 최신 코드를 가져옵니다 (-SkipGitPull 제외)
기존 예약된 작업을 중지하고 3000번 포트를 정리합니다
작업을 재시작하여 앱을 다시 빌드하고 서비스하도록 합니다
localhost:3000이 응답할 때까지 최대 180초 동안 대기합니다

로그는 logs/service-watchdog.log 및 logs/start-service-child.log에 기록됩니다.

Ubuntu/Debian에서 지속적인 배포를 하려면 scripts/deploy.sh를 사용하세요. 이 스크립트는 첫 실행 시 systemd 유닛을 설치하고, 이후 실행 시 배포를 업데이트합니다.

# 머신에서의 첫 실행 (유닛 설치, 빌드, 자동 시작 활성화, 시작)
sudo ./scripts/deploy.sh
# 이후 업데이트: git pull + npm ci + 빌드 + 재시작 + 상태 확인
...

서비스는 스크립트를 호출한 사용자로 실행됩니다. 즉, sudo ./scripts/deploy.sh를 실행하면 모든 것(git, npm, Node 프로세스)이 root 권한으로 실행됩니다. 다른 사용자를 원한다면 해당 사용자로 스크립트를 직접 실행하세요 (단, systemctl 접근 권한을 부여하기 위한 별도의 경로, 예: polkit이 여전히 필요합니다).

서비스 관리:

sudo systemctl status agents-chat
sudo systemctl restart agents-chat
sudo systemctl stop agents-chat
...

환경 변수 (Environment variables)는 두 개의 파일에서 로드됩니다 (나중에 로드된 파일이 우선합니다):

프로젝트 루트의 .env.local — Next.js가 읽는 것과 동일한 파일입니다. systemd는 이를 유닛의 환경으로 로드하여, Node가 시작되기 전에 npm start가 PORT, LOG_* 등을 볼 수 있게 합니다.
(선택 사항) /etc/agents-chat.env — .env.local보다 우선순위가 높은 머신 레벨 (machine-level) 오버라이드 파일입니다.

systemd의 EnvironmentFile 파서는 줄당 KEY=value 또는 KEY="value" 형식을 허용합니다. export KEY=..., 단일 인용부호('), 또는 ${VAR} 보간 (interpolation)은 지원하지 않습니다. 유닛이 이를 읽기를 원한다면 .env.local을 단순한 KEY=VALUE 줄로 유지하십시오.

sudo tee /etc/agents-chat.env > /dev/null <<EOF
PORT=8080
LOG_LEVEL=debug
...
EOF

서버는 구조화된 로그 (structured logs)를 위해 pino + pino-roll을 사용합니다. 기본값은 다음과 같습니다:

변수 (Variable)	기본값 (Default)	설명 (Description)
`LOG_LEVEL`	`info` (prod) / `debug` (dev)	`trace` / `debug` / `info` / `warn` / `error` / `fatal`
`LOG_DIR`	`<project>/logs`	절대 경로 또는 상대 경로
`LOG_FILE`	`app.log`	기본 파일 이름
`LOG_ROTATE_FREQUENCY`	`daily`	`daily` / `hourly` / 밀리초 (milliseconds)
`LOG_ROTATE_SIZE`	`10m`	중간 주기 로테이션 전 최대 크기
`LOG_RETENTION`	`7`	유지할 로테이션된 파일 수

$LOG_DIR 아래에 기록되는 파일:

app.<date>.<n>.log — pino 구조화된 JSON (로테이션됨)

Linux에서는 stdout/stderr 또한 journald에 의해 캡처됩니다 (journalctl -u agents-chat).

멀티 에이전트 채팅 (Multi-agent chat) — 하나의 ACP 에이전트와 대화하거나 한 메시지 내에서 여러 에이전트를 언급할 수 있습니다.
@mention 라우팅 (@mention routing) — @agent-id를 입력하여...

특정 에이전트를 대상으로 지정할 수 있습니다. 멘션이 없는 메시지는 현재 선택된/기본 에이전트에게 전달됩니다.

자동 에이전트 오케스트레이션 (Auto agent orchestration)— 스케줄러 에이전트가 다음에 어떤 에이전트가 동작해야 할지 결정하고, 결과를 평가하며, 최종 요약을 생성합니다.

토론 오케스트레이션 (Discussion orchestration)— 설정 가능한 라운드 동안 여러 에이전트를 병렬로 실행한 후 요약합니다.

파이프라인 오케스트레이션 (Pipeline orchestration)— 에이전트를 순차적으로 실행하며, 각 출력을 다음 에이전트로 전달합니다.

파일 첨부 (File attachments)— 드래그 앤 드롭하거나 클릭하여 메시지에 이미지 및 파일을 첨부할 수 있습니다 (최대 8개 파일, 각 파일당 10MB까지).

파일 탭 (Files tab)— 에이전트의 작업 디렉토리(로컬 또는 원격/릴레이 에이전트)를 탐색하고, 변경된 파일로 필터링하며, 파일을 인라인으로 열거나, 분할 미리보기 또는 라이브 편집 기능을 통해 Markdown을 편집하고 변경 사항을 디스크에 다시 저장할 수 있습니다. 릴레이 에이전트의 경우 백엔드가 노드에 자동으로 연결하고 원격 머신에서 cwd를 해결합니다.

모델 선택 (Model selection)— 에이전트가 사용 가능한 모델과 동기화된 에이전트별 모델 선택기입니다.

슬래시 명령어 (Slash commands)— 단일 에이전트 채팅에서 /를 입력하여 에이전트의 ACP(Agent Communication Protocol)로 광고된 슬래시 명령어를 선택할 수 있습니다 (자동 완성 드롭다운).

앱 내 ACP 로그인 (In-app ACP sign-in)— 인증이 필요한 에이전트(예: Copilot CLI)는 UI에 직접 로그인 흐름을 노출합니다. 인증 누락으로 인해 턴(turn)이 실패하면 컴포저(composer)가 needs auth 알림을 표시하며, 로그인이 실제로 성공했는지 확인합니다.

스케줄러 / 크론 작업 (Scheduler / cron jobs)— 테마가 적용된 시간 선택기, 작업별 실행 타임아웃, 사용자의 로컬 시간대로 렌더링되는 예약 시간을 사용하여 크론 표현식(cron expression)에 따라 모든 에이전트의 실행을 예약할 수 있습니다.

환경 변수 (Environment variables)— API 키 및 에이전트 설정을 위한 에이전트별 KEY=VALUE 구성입니다.

테마 (Themes)— 5가지 내장 테마 (Aurora, Sunset, VS Code Dark, Claude, ChatGPT).

메시지 작업 (Message actions)— 복사 (일반 텍스트), 서식 포함 복사 (Copy with format) (생각(thinking) 및 도구 호출(tool-call) DOM을 제외한 리치 Markdown → HTML/Markdown), 재시도, 또는 모든 메시지로부터 브랜치(branch) 생성이 가능합니다.

멘션 자동 완성 (Mention autocomplete)— @를 입력하면

입력하는 동안 에이전트 드롭다운 목록이 필터링됩니다. 전체 화면 전환 (Full screen toggle)— 채팅을 전체 화면으로 확장하는 헤더 버튼 (데스크톱 + 모바일). 멀티턴 큐 (Multi-turn queue)— 에이전트가 처리 중인 동안 후속 메시지를 보낼 수 있습니다. 턴(turn)은 큐에 쌓이며 순서대로 실행됩니다. 스트리밍 응답 (Streaming responses)— 사고(thinking), 도구 실행(tool execution), 응답(replying) 단계별 표시가 포함된 실시간 스트리밍. 에이전트 관리 (Agent management)— UI에서 에이전트를 추가, 구성, 제거 및 권한을 설정할 수 있습니다. "마지막 사용 에이전트"는 서버에서 사용자별로 유지됩니다. 릴레이 에이전트 (Relay agents)— Azure Relay를 통해 다른 머신의 원격 에이전트에 연결합니다. 노드 레지스트리 (Node registry)— 원격 에이전트 노드를 등록하고 검색합니다. Azure Relay 하이브리드 연결을 자동으로 검색합니다. Node Setup Kit을 통해 런처(Copilot CLI 또는 Agency)를 선택할 수 있습니다. 채팅 기록 (Chat history)— SQLite (.data/chats.db)에 저장되는 영구적인 메시지 기록으로, 사이드바에 실행 상태가 표시되며 최신순으로 정렬되고 로그인한 사용자로 필터링됩니다. 세션 재개 (Session resume)— 채팅을 다시 불러오면 session/load를 통해 에이전트 세션 컨텍스트가 복구됩니다. 공유 채팅 (Shared chats)— 모든 대화에 대해 읽기 전용 공유 링크를 생성하며, Teams 미리보기에 최적화된 Open Graph 이미지를 제공합니다. 모바일 반응형 (Mobile responsive)— 스와이프 가능한 패널과 터치 친화적인 컨트롤을 갖춘 휴대폰 및 태블릿용 풀 기능 UI. 인증 (Authentication)— Azure AD SSO, GitHub OAuth 또는 로컬 자격 증명 로그인; 관리자/사용자 역할.

왼쪽 채팅 (Chats) 사이드바에서 채팅을 선택하거나 생성합니다.
일반 메시지를 입력하면 기본 선택된 에이전트에게 메시지가 전송됩니다.
@agent-id를 입력하여 특정 에이전트에게 메시지를 라우팅합니다.
예를 들어 @frontend @reviewer implement and review this change와 같이 여러 에이전트를 멘션하여 컴포저(composer)에서 오케스트레이션(orchestration) 제어 기능을 활성화할 수 있습니다.

채팅 사이드바는 각 채팅의 최근 상태를 보여주므로, 턴이 실행되는 동안 다른 채팅으로 전환하더라도 해당 상태가 Running (실행 중), Done (완료), 또는 Error (오류)인지 확인할 수 있습니다.

메시지에 하나 이상의 에이전트가 멘션되면, 컴포저에 오케스트레이션 모드가 나타납니다:

Auto (자동)— 스케줄러 에이전트 (scheduler agent)가 다음 단계를 계획하고, 언급된 에이전트 중 하나를 선택하며, 그 결과를 기다린 다음, 다른 에이전트를 실행할지 또는 최종 요약을 생성할지를 결정합니다. Discussion (토론)— 언급된 모든 에이전트가 병렬로 응답합니다. 토론 라운드 횟수를 선택할 수 있습니다. 마지막 라운드 후에 요약이 생성됩니다. Pipeline (파이프라인)— 에이전트들이 언급된 순서대로 실행됩니다. 각 에이전트는 이전 에이전트의 출력을 전달받습니다.

Auto 모드는 "한 에이전트에게 구현을 요청한 다음, 결과에 따라 다른 에이전트가 테스트/검토하도록 한다"와 같이 작업에 조건부 흐름 (conditional flow)이 있을 때 유용합니다. 스케줄러는 라우팅 (routing) 전용입니다. 즉, 스케줄러는 직접 프로젝트 작업을 수행하기보다는 에이전트를 선택하고 지침을 작성해야 합니다.

단일 에이전트를 대상으로 하는 채팅에서는 컴포저 (composer)에서 /를 입력하여 해당 에이전트의 ACP로 광고된 슬래시 명령어 (slash commands) 드롭다운을 열 수 있습니다. 하나를 선택하면 명령어가 삽입되며, 인자 (arguments, 있는 경우)는 그 뒤에 입력할 수 있습니다. 슬래시 명령어는 채팅이 정확히 하나의 에이전트를 대상으로 할 때만 표시됩니다.

모든 에이전트는 크론 표현식 (cron expression)에 따라 실행되도록 예약할 수 있습니다:

에이전트의 설정 또는 Scheduler (스케줄러) UI를 엽니다.
테마가 적용된 피커 (picker)를 사용하여 크론 일정을 선택합니다 (시간은 사용자의 로컬 시간대로 표시됩니다).
선택 사항인 **per-job run timeout (작업당 실행 제한 시간)**을 설정하여, 멈춘 작업이 자동으로 취소되도록 합니다.
저장합니다. 작업은 일정에 따라 실행되어 에이전트를 대상으로 한 턴 (turn)을 수행하고 결과를 기록합니다.

일부 ACP 에이전트(예: GitHub Copilot CLI)는 프롬프트에 응답하기 전에 인증 (authentication)이 필요합니다. 에이전트가 인증이 필요하다고 보고하면:

컴포저에 needs auth (인증 필요) 필 (pill)이 나타납니다.
에이전트 패널을 열고 **Sign in (로그인)**을 클릭합니다. UI는 에이전트의 authenticate ACP 흐름을 실행하며, 필을 제거하기 전에 로그인이 실제로 완료되었는지 확인합니다.

왼쪽 사이드바에는 **Chats (채팅)**와 Files (파일) 두 개의 탭이 있습니다.

**Files (파일)**를 사용하여 모든 에이전트의 작업 디렉토리(로컬 또는 릴레이)에 있는 파일을 검사하고 편집할 수 있습니다:

Files 탭을 엽니다. - 드롭다운에서 에이전트를 선택합니다. 릴레이 에이전트 (Relay agents)가 지원됩니다 — 백엔드가 노드에 자동으로 연결하고 원격 머신에서 작업 디렉토리 (working directory)를 확인합니다.
파일 트리 (file tree)를 탐색합니다. 백엔드는 .git, node_modules, .next, dist, build와 같은 무거운/생성된 폴더 및 바이너리/미디어 파일 확장자를 건너뜁니다. - 파일을 클릭하면 인라인 (inline)으로 열립니다.
마크다운 (Markdown) 파일의 경우 다음을 선택할 수 있습니다:
Split — 텍스트 에디터와 렌더링된 미리보기를 함께 제공합니다. Live Edit — 편집 가능한 렌더링된 마크다운을 제공합니다.
Save를 클릭하여 변경 사항을 에이전트의 작업 디렉토리 (working directory)에 다시 씁니다.

Diff / Changed 토글은 git에 따라 변경된 파일만 나열합니다 (git diff --name-only HEAD 및 추적되지 않은 파일 포함). 파일 목록에 더 이상 인위적인 파일 수 제한이 없지만, 최대 깊이 및 건너뛴 디렉토리/확장성과 같은 탐색 안전 장치 (traversal safety guards)는 여전히 유지됩니다.

.env.example을 .env.local로 복사하고 필요한 값을 채우세요:

cp .env.example .env.local

변수 (Variable)	필수 여부	설명
`NEXTAUTH_SECRET`	✅	JWT 서명을 위한 랜덤 비밀 값 (Random secret)
`NEXTAUTH_URL`	✅	앱의 공개 URL (예: `https://localhost:3010`)
`AZURE_AD_CLIENT_ID`	선택 사항	Azure AD / Microsoft Entra 앱 클라이언트 ID (client ID); 설정 시 SSO 로그인을 활성화합니다
`AZURE_AD_CLIENT_SECRET`	선택 사항	Azure AD 클라이언트 비밀 값 (client secret)
`AZURE_AD_TENANT_ID`	선택 사항	테넌트 ID (Tenant ID), 기본값은 `common`
`GITHUB_CLIENT_ID`	선택 사항	GitHub OAuth 앱 클라이언트 ID (client ID); 설정 시 "GitHub로 로그인"을 활성화합니다. OAuth 앱의 콜백 URL (callback URL)을 `${NEXTAUTH_URL}/api/auth/callback/github`로 구성하세요.

에이전트 (Agents)는 SQLite (.data/config.db)에 저장되며 UI를 통해 관리됩니다. 첫 부팅 시 앱은 기존의 agents.json 파일을 자동으로 마이그레이션 (migrate)합니다.

오른쪽의 Agents 패널을 엽니다.
**+**를 클릭합니다.
Add Agent in Server를 선택합니다. 이 옵션은 앱 서버에서 프로세스를 시작하기 때문에 관리자 전용입니다.
다음 항목을 입력합니다:
Agent ID— @mentions에 사용되는 고유한 소문자 식별자.
Display Name— UI에 표시될 사용자 친화적인 이름.
Command— ACP 호환 실행 파일 (예: copilot.exe) 또는 절대 경로.
Arguments— 공백으로 구분된 인자 (arguments), 일반적으로 --acp 사용.
Working Directory— 에이전트가 실행될 프로젝트 폴더.
YOLO mode— 자동 승인 모드; 백엔드에서 지원되는 경우 관련 yolo 플래그 (flag)를 추가합니다.
Create Agent를 클릭합니다.

huanyingtianhe/agents-chat

요약

핵심 포인트

댓글