# Chat API
SUMMARY: 사람과 LLM 에이전트 간의 비동기 채팅 — 폴링, 응답, 기록, 읽지 않은 메시지 수, 파일 업로드.

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

Chat API
Chat API는 사람과 LLM 에이전트 간의 비동기 메시징을 지원합니다.
동기식 채팅(ChatGPT 스타일)과 달리, 사람은 에이전트가 작업 중인 동안에도
메시지를 남길 수 있으며 — 에이전트는 도구 호출 사이에 폴링합니다.
작동 방식
[CODE BLOCK]
1. 사람이 웹 UI를 통해 메시지를 전송합니다 (JWT 사용)
2. 메시지가 저장되고 읽지 않음으로 표시됩니다
3. 에이전트는 도구 호출 사이에 을 폴링합니다
4. 폴링은 모든 읽지 않은 메시지를 반환하고 읽음으로 표시합니다
5. 에이전트는 메시지를 처리하고, 선택적으로 로 응답합니다
엔드포인트
GET /chat/poll
사람이 보낸 새 메시지를 폴링합니다. 읽지 않은 메시지를 반환하고 읽음으로
표시합니다. 도구 호출 사이에 사용하십시오.
[CODE BLOCK]
응답:
[CODE BLOCK]
POST /chat/reply
에이전트로 메시지를 전송합니다.
[CODE BLOCK]
POST /chat/send
사람으로 메시지를 전송합니다 (Mind Key가 아닌 JWT 필요).
[CODE BLOCK]
GET /chat/history
최근 채팅 기록을 가져옵니다 (양쪽 역할 모두).
[CODE BLOCK]
GET /chat/unread
읽지 않은 메시지 수를 가져옵니다.
[CODE BLOCK]
GET /chat/status
채팅 세션 상태를 가져옵니다 (마지막 메시지 타임스탬프, 읽지 않은 메시지 수).
[CODE BLOCK]
POST /chat/upload
특정 메시지의 파일 첨부를 업로드합니다 (multipart 폼).
[CODE BLOCK]
GET /chat/files/:messageid
메시지의 파일 첨부 목록을 조회합니다.
[CODE BLOCK]
GET /chat/file/:fileid
파일 첨부를 다운로드합니다.
[CODE BLOCK]
폴링 패턴
> [!TIP]
> 도구 호출 사이에 30-60초마다 폴링하십시오. 더 자주 폴링하지 마십시오 —
> API 할당량을 낭비하고 이점이 없습니다.
[CODE BLOCK]
다음 단계
- Tasks API
- Chat Polling Pattern