# AI 에이전트 설정

> AI 코딩 에이전트가 서버 등록과 읽기 전용 에이전트 설치를 수행하도록 안내하는 프롬프트입니다.

## 개요

아래 프롬프트를 AI 코딩 에이전트에 전달하면 프로젝트 서버 등록, 설치, 상태 확인 순서를 안내할 수 있습니다.
프롬프트 자체에는 API key나 server token 같은 secret이 없습니다. 에이전트는 `THESEEKER_API_KEY` 환경 변수에서 키를 읽고, 값이 없으면 키 파일 경로를 물어봐야 합니다.

## 프롬프트

```text
Read and follow: https://docs.theseeker.io/server-monitoring/ai-agent-setup.md

<context>
- API base URL: https://crm.theseeker.io/api/v1
- API 키: 환경 변수 THESEEKER_API_KEY 로 전달합니다. 설정돼 있지 않으면 키 파일 경로를 저에게 물어보세요. 키 값은 절대 출력하지 마세요.
- 프로젝트 slug: <project-slug>
- 서버 이름: <server-name> (slug: <server-slug>)
- 대상 호스트: <ssh-user@host> (Ubuntu/Debian, systemd)
</context>

<instructions>
1. 키 확인: `GET /api/v1/servers?projectSlug=<project-slug>` 를 `Authorization: Bearer $THESEEKER_API_KEY` 로 호출해 200 을 확인합니다. 401/403 이면 중단하고 저에게 알립니다.
2. 서버 등록: `POST /api/v1/servers` 에 `{"projectSlug":"<project-slug>","name":"<server-name>","slug":"<server-slug>"}` 를 보냅니다. 응답의 `token`(1회성, `sa_` 로 시작), `agentEndpoint`, `install` 스니펫을 사용합니다. 토큰은 메모리 또는 mode-600 임시 파일에만 둡니다.
3. 에이전트 설치(대상 호스트, Node.js 20+): `sudo npm i -g @the-seeker/server-agent@latest` 후 `sudo theseeker-agent install --token <token> --endpoint <agentEndpoint> --user $USER`. `node` 가 nvm 으로만 설치돼 `sudo npm` 이 실패하면, 로그인 사용자로 `npm i -g @the-seeker/server-agent@latest` 를 실행한 뒤 `sudo "$(command -v node)" "$(command -v theseeker-agent)" install --token <token> --endpoint <agentEndpoint> --user $USER` 를 실행합니다(systemd 유닛의 ExecStart 에 node 절대 경로가 포함됩니다). 사용자가 `adm`, `systemd-journal` 그룹에 없으면 `--add-groups` 를 붙입니다.
4. PM2 감시 확인: 대상 호스트에서 PM2 를 쓰면 `--user` 는 PM2 데몬 소유자(`ps -eo user,cmd | grep "PM2 v"`)여야 합니다. 설치 후 대시보드에 "PM2 미설치" 가 보이는데 `pm2 list` 는 되는 경우, node/pm2 가 nvm 에 있어 서비스 PATH 에서 보이지 않는 것입니다. `@the-seeker/server-agent@latest`(0.1.1 이상)로 올리고 같은 install 명령을 다시 실행하면 systemd 유닛에 `Environment=PATH=<node bin 디렉터리>:…` 가 기록됩니다. 0.1.2 미만은 이어서 `sudo systemctl restart theseeker-agent` 를 실행합니다.
5. 검증: 호스트에서 `theseeker-agent status` 가 active 를 보고하고, `GET /api/v1/servers/<id>` 가 60초 안에 `"state":"online"` 을 반환해야 합니다.
</instructions>

<constraints>
- API 키와 `sa_` 토큰을 출력·로그·커밋하지 않습니다. 토큰을 담았던 임시 파일은 삭제합니다.
- 호스트의 다른 설정을 변경하지 않습니다. 예상치 못한 오류(2xx 가 아닌 응답, 설치 실패, 서비스 비활성)가 나면 중단하고 저에게 알립니다.
</constraints>

<verification>
보고: 서버 id, slug, state(online/offline), 호스트의 `theseeker-agent status` 출력, 그리고 지시와 달라진 점.
</verification>
```

## 동작 흐름

1. 환경 변수의 키로 서버 목록을 조회해 인증과 프로젝트 범위를 확인합니다.
2. `POST /api/v1/servers`가 1회성 `sa_` 토큰과 설치 스니펫을 반환합니다.
3. 대상 호스트에 패키지를 설치하고 systemd 에이전트를 등록합니다.
4. PM2 소유자 사용자와 nvm PATH 를 확인해 PM2 감시가 켜졌는지 봅니다.
5. 로컬 상태와 REST 상세 응답에서 `online`을 확인합니다.

## 필요한 권한

프로젝트 키에는 `servers:write`가 필요합니다. 조직 키는 `servers:write` 또는 `admin:write`를 사용할 수 있습니다.

## 문제 해결

`401`은 Bearer 형식이나 secret을 확인하세요. `403`은 `servers:write`와 프로젝트 범위를 확인하세요.
`409`는 서버 slug가 이미 사용 중이라는 뜻입니다. `429`에서는 `Retry-After`만큼 기다립니다.
nvm 전용 호스트는 위 nvm 명령을 사용하고, 로그가 비어 있으면 `--add-groups`를 검토하세요.
설치 후 90초 동안 heartbeat가 없으면 `offline`으로 표시됩니다.
`PM2 미설치` 가 보이면 서비스 사용자가 PM2 소유자인지와 에이전트 버전(0.1.1 이상)을 확인하세요.