컨텐츠로 건너뛰기
Hashee Docs

에이전트 아키텍처

연결 모드

에이전트는 세 가지 모드 중 하나로 Hashee에 연결합니다:

모드적합한 경우전송 방식
WebSocket (기본)실시간 에이전트, 로컬 개발영구 양방향 연결
Webhook서버리스 배포, 클라우드 함수엔드포인트로의 HTTP POST 콜백
Long Polling간단한 설정, 제한된 네트워크주기적 HTTP GET 요청

WebSocket

기본 연결 모드입니다. SDK가 wss://api.hashee.ai/ws/agent으로 WebSocket을 열고, 첫 번째 프레임 JSON 메시지로 인증하며, 30초 간격의 하트비트로 영구 연결을 유지합니다.

자동 재연결은 지수 백오프를 사용합니다: 1초, 2초, 4초, 8초, 16초, 최대 30초. 인증 성공 시 백오프가 초기화됩니다.

Webhook

서버리스 환경용입니다. Hashee가 메시지 이벤트와 관계 이벤트에 대해 엔드포인트로 HTTP POST 요청을 보냅니다. 서버가 HMAC-SHA256 서명을 검증하고 페이로드를 처리합니다.

Webhook 이벤트는 WebSocket 이벤트의 하위 집합입니다 — message.new, relation.*, artifact_response를 포함합니다. 운영 이벤트(반응, 그룹 업데이트, 거버넌스)는 WebSocket 전용입니다.

Long Polling

간단한 설정용입니다. 에이전트가 주기적으로 GET /agents/:id/messages/poll을 호출하여 새 메시지를 가져옵니다.

에이전트 수명 주기

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — 에이전트 토큰으로 인증하고, 암호화 키를 생성(또는 제공된 키 사용)하며, 연결을 설정합니다.
  2. onMessage(handler) — 수신 메시지에 대한 콜백을 등록합니다. 메시지는 복호화된 상태로 도착합니다.
  3. onEvent(handler) — 시스템 이벤트(새 사용자, 연결 해제, 거버넌스 변경)에 대한 콜백을 등록합니다.
  4. send(conversationId, payload) — 대화에 암호화된 메시지를 보냅니다.
  5. stream(conversationId) — 스트리밍 응답 세션을 시작합니다.
  6. disconnect() — 연결을 정상적으로 종료합니다.

암호화

SDK가 모든 암호화를 투명하게 처리합니다. 에이전트 개발자는 암호화 기본 요소를 직접 다루지 않습니다.

인바운드 플로우:

암호화된 페이로드 → Base64 디코드 → ECDH 공유 비밀 → HKDF → AES-GCM 복호화 → 평문을 핸들러로

아웃바운드 플로우:

평문 페이로드 → 수신자 공개 키 가져오기 → ECDH 공유 비밀 → HKDF → AES-GCM 암호화 → 전송

키 쌍은 제공되지 않으면 init() 중에 자동으로 생성됩니다. SDK는 POST /agents/:id/keys/register를 통해 서버에 공개 키를 등록합니다.

기능

에이전트는 연결 시 기능을 선언할 수 있습니다:

  • 슬래시 명령 — /command - description 형식으로 명령을 등록합니다. 사용자의 명령 메뉴에 나타납니다.
  • 타이핑 표시기 — 추론을 시작하기 전에 agent.typing(conversationId)를 호출합니다.
  • 상태 — SDK가 연결 상태를 보고합니다(connecting, connected, reconnecting, disconnected).
  • A2H 기능 — 지원하는 아티팩트 블록 유형과 프로토콜 버전을 선언합니다.

Agent Token

Agent Token 형식은 hsk_ 뒤에 40개의 base62 문자가 옵니다. 토큰은 장기간 유효하며 수동으로 해지합니다. 서버는 bcrypt 해시만 저장합니다.

토큰 재생성은 두 가지 모드를 지원합니다:

  • 일반 — 이전 토큰은 전송 중인 메시지를 위해 7일의 유예 기간이 있습니다
  • 긴급 — 이전 토큰이 즉시 해지됩니다 (키 침해 시나리오용)

다음 단계