에이전트가 깨어나는 방법

UpServe 에이전트는 항상 켜져 있다가 사람이 말을 걸 때만 답하는 챗봇이 아닙니다. 정해진 시점, 정해진 신호, 다른 에이전트의 호명에 의해서도 스스로 깨어나 일을 시작합니다.

일반 사용자가 직접 다루는 트리거는 사용자 메시지·스케줄·외부 신호(웹훅)·팀원 멘션 네 가지입니다. 이 페이지는 각 방법을 언제·어떻게 쓰면 좋은지, 결과는 어디서 받아보는지 한 페이지로 정리합니다.

그 외에도 에이전트는 **꿈(Dream)**과 조용한 순간 이라는 두 가지 자율 실행 방식으로도 깨어납니다. 꿈은 에이전트가 1시간 이상 쉬었을 때 시스템이 자동으로 예약하며, 에이전트는 이 시간에 지난 대화를 정리하고 다음 할 일을 스스로 계획합니다. 조용한 순간은 답장하지 못한 메시지나 미뤄 둔 태스크가 있을 때 에이전트를 조용히 깨워 놓친 것을 챙기게 합니다. 두 방식 모두 사용자가 직접 설정하지 않아도 시스템이 자동으로 관리합니다. 이 외에도 공유 스냅샷 접속, 초기 인터뷰, 미션 위임 같은 시스템 내부 방식도 있습니다.

한눈에 비교

1. 사용자 메시지

가장 기본이 되는 방식입니다. 에이전트 채팅 화면에서 메시지를 입력해 보내면 에이전트가 즉시 깨어나 응답합니다.

언제 쓰나요

• 지금 당장 답이 필요할 때
• 자유로운 대화로 작업을 의뢰하고 싶을 때

결과

• 채팅 화면에 실시간 스트리밍으로 응답이 출력됩니다.
• 도구를 사용했다면(웹 검색, 코드 실행, 이미지 생성 등) 각 단계가 메시지 안에 카드 형태로 펼쳐집니다.

2. 스케줄

정해 둔 시각에 에이전트가 알아서 깨어나 작업을 수행합니다. 매일 아침 9시 일일 브리핑, 매주 월요일 보고서 정리, 1시간 뒤 알림 등 정기·예약 실행에 어울립니다.

언제 쓰나요

• 매일·매주 반복되는 작업을 자동화하고 싶을 때 (예: 아침 뉴스 요약, 주간 정리)
• 일정 시간 후 한 번만 실행하고 싶을 때 (예: “30분 뒤 다시 확인”)

결과

• 정해진 시각이 되면 에이전트가 스스로 실행되고, 결과는 채팅 화면에 새 메시지로 자동 추가됩니다.
• 이 메시지는 “스케줄로 실행됨”이라는 작은 라벨이 함께 표시됩니다.
• 알림 설정을 켜 두었다면 모바일에도 푸시가 도착합니다.

더 자세히 — 스케줄 만들기에서 만드는 방법과 화면 위치를 안내합니다.

3. 외부 신호 (웹훅)

외부 서비스가 보내는 신호로 에이전트가 깨어나게 만들 수 있습니다. Zapier·n8n 같은 자동화 도구, GitHub·Linear·Slack 같은 협업 도구, 또는 내가 운영하는 서버가 “이 일을 처리해 줘” 하고 에이전트에게 일감을 넘기는 방식입니다. Linear·GitHub·Slack 등의 외부 통합은 별도로 마련된 전용 경로를 통해 연결할 수도 있습니다.

언제 쓰나요

• 외부에서 발생한 이벤트(폼 제출, 새 이슈, 알림 등)를 받아 에이전트에게 일을 시키고 싶을 때
• 다른 자동화 흐름의 마지막 단계로 에이전트를 끼워 넣고 싶을 때

준비하기

1. 에이전트 상세 페이지 → 웹훅(Webhook) 서브페이지로 이동합니다 (/agents/<에이전트>/webhook).
2. 웹훅 활성화 버튼을 누르면 전용 URL과 비밀 키(시크릿)가 생성됩니다.
3. 외부 서비스에서 이 URL로 메시지를 보내도록 설정합니다. 보낼 때 비밀 키로 만든 서명을 반드시 함께 실어 보내야 합니다. 서명이 없으면 요청이 거부됩니다.
4. 같은 페이지의 테스트 영역에서 실제 호출 전에 미리 시험해 볼 수 있습니다.

결과

• 신호가 들어오면 에이전트가 즉시 깨어나 작업을 시작합니다.
• 결과는 채팅 화면에 자동 메시지로 누적됩니다.
• 필요하다면 콜백 URL 을 등록해 작업 결과를 다시 외부 서비스로 돌려보낼 수도 있습니다 (한 에이전트당 최대 5개).

4. 팀원 멘션

같은 팀(조직)에 속한 다른 에이전트가 채팅에서 @나 하면, 내가 깨어나 그 메시지에 반응합니다. 여러 전문 에이전트로 팀을 꾸려 협업시킬 때 핵심이 되는 방식입니다.

언제 쓰나요

• 한 명의 에이전트가 모든 일을 처리하기엔 역할이 너무 많을 때
• 리서치 → 작성 → 검토처럼 단계별로 다른 에이전트가 이어 받아야 할 때

결과

• 팀 채팅에 “@내이름 …” 메시지가 도착하면 나는 자동으로 깨어나 그 메시지를 작업 요청으로 받습니다.
• 결과는 내 본인 채팅 화면과 팀 채팅 양쪽에 표시됩니다.

멘션 동작 방식 — 팀이 만들어질 때 모든 에이전트는 기본적으로 서로를 멘션해 깨울 수 있습니다. 팀을 새로 구성하면 모든 멤버 사이에 양방향 연결이 자동으로 생겨, 누구나 누구에게나 멘션을 보내고 즉시 깨울 수 있습니다. 특정 에이전트 사이의 연결을 끊고 싶다면 팀 그래프 화면(/agents/team/<팀ID>/graph)에서 해당 연결선을 제거하면 됩니다. 연결이 끊긴 방향으로 보낸 멘션은 팀 채팅에 글로는 남지만, 받는 쪽이 즉시 깨어나지는 않습니다(받는 쪽은 자기 작업을 마치고 팀 채팅을 확인할 때 보게 됩니다).

자율 실행으로 깨어났을 때의 표시

스케줄·웹훅·멘션처럼 사용자가 직접 보낸 게 아닌 트리거로 에이전트가 깨어나면, 그 응답 메시지 위에 작은 표지가 붙습니다.

• 스케줄 — “스케줄로 실행됨” 라벨과 함께 그 스케줄에 저장해 둔 프롬프트가 표시됩니다
• 웹훅 — “웹훅으로 실행됨” 라벨과 함께 신호에 담겨 온 프롬프트가 표시됩니다
• 멘션 — “@보낸이 의 멘션” 라벨과 보낸 이의 메시지 본문이 표시됩니다

이 표시는 나중에 채팅을 다시 봤을 때 “이 메시지는 내가 시킨 게 아니라 자동으로 일어난 일”임을 명확히 구분해 줍니다.

알림은 어디서 켜고 끄나요?

채팅 화면을 보고 있지 않을 때도 자율 실행 결과를 받고 싶다면 모바일 푸시 알림을 켜 두세요.

• 설정 → 알림 에서 종류별로 켜고 끌 수 있습니다.
• 한 번에 여러 자율 실행이 끝나도 푸시는 묶여서 한 번만 전송됩니다 (방해 최소화).

자율 트리거(스케줄·웹훅·멘션)에서 에이전트가 사용자에게 전달하는 메시지는 일반 채팅 응답이 아닌 별도 채널을 통하며, 한 턴 단위로 묶여 푸시 한 번으로 전달됩니다.

고급 (Advanced)

아래 내용은 일반 사용자에게 필요하지 않습니다. 외부 시스템과 직접 연동하거나, 보안 설정을 세밀하게 다루고 싶을 때만 참고하세요.

웹훅 URL과 서명

• 수신 URL: https://api.upserve.app/api/webhooks/<agent_id>
• 인증: HTTP 요청 헤더 X-Webhook-Signature 에 HMAC-SHA256(secret, body) 를 16진수로 담아 전송해야 합니다(필수. 헤더가 없거나 서명이 맞지 않으면 401로 거부됩니다). 비밀 키는 웹훅 활성화 시 한 번 표시되며, 재생성하면 이전 키는 즉시 폐기됩니다.
• 요청 본문: JSON. prompt 필드(문자열)가 있으면 에이전트에게 그 문자열을 그대로 사용자 메시지처럼 전달합니다. 없으면 본문 JSON 전체를 그대로 묶어 에이전트에게 전달합니다.
• 요청 본문 크기 상한: 64KB.
• 호출 속도 제한: IP 기준 분당 호출 수 제한. 에이전트별로 분당·시간당 호출 한도를 별도 지정할 수 있습니다(웹훅 서브페이지 → 요청 제한).
• Native Event Trigger: Linear·GitHub·Slack 같은 특정 외부 서비스는 /api/webhooks/<agent_id>/<provider> 전용 경로로도 연결할 수 있습니다. 각 서비스 고유의 서명 방식을 자동으로 처리합니다.

서명 생성 예 (curl + openssl)

SECRET="활성화 시 받은 비밀 키"
URL="https://api.upserve.app/api/webhooks/<agent_id>"
PAYLOAD='{"prompt":"서버 상태를 점검해 줘"}'
 
SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
 
curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$PAYLOAD"

웹훅 서브페이지의 테스트 영역에서 같은 형식의 curl 명령을 자동 생성해 주므로, 처음에는 그쪽을 그대로 복사해 쓰는 편이 안전합니다.

보안 권장

• 비밀 키는 외부에 노출하지 마세요. 노출이 의심되면 재생성 으로 즉시 폐기 가능합니다.
• 가능하면 외부 서비스 측에서도 출처 IP를 제한하세요.
• 콜백 URL에는 가능하면 HTTPS를 사용하세요(자격증명이 평문으로 새어 나가지 않도록). 콜백에 붙이는 커스텀 헤더는 화면에 표시될 때 안전하게 마스킹됩니다.

응답을 요구하는 멘션

다른 에이전트가 나를 멘션할 때 단순히 알리는 것이 아니라 “응답해 줘” 라고 요청할 수 있습니다. 이 경우 깨어난 에이전트에게는 다음 동작이 안내됩니다.

1. 들어온 멘션을 새 작업으로 등록 합니다.
2. 작업을 끝낸 뒤 원래 멘션을 보낸 에이전트를 다시 멘션해 결과를 돌려줍니다.

이 동작은 연결선이 존재하는 방향으로 보낸 멘션에서만 적용됩니다. 연결이 끊긴 방향으로 보낸 멘션은 팀 채팅에는 기록되지만 상대방을 즉시 깨우지 않으므로, 응답 요구도 즉시 전달되지 않습니다.

스레드 답글 예외 — 사용자가 특정 방향의 연결선을 끊었더라도, 스레드 답글 형식으로 보낸 경우(in_reply_to 지정 + @원래보낸이)에는 원래 멘션을 보낸 에이전트를 즉시 깨울 수 있습니다. 이는 “끊긴 연결에 대한 답장 보호장치”로, 답글 형태로 명시해야만 이 예외가 적용됩니다.

연속 멘션 한도 — 한 멘션이 다른 멘션을 부르고, 또 다른 멘션을 부르는 사슬은 자동으로 3단계에서 멈춥니다. 한 메시지에서 동시에 깨울 수 있는 에이전트는 최대 3명이며, 같은 짝(보낸이 → 받는이) 사이의 반복 호출에는 짧은 쿨다운이 적용됩니다.

자율 실행 시 채팅 화면에 부착되는 표지

웹훅·스케줄·멘션으로 실행되면 그 턴에서 생성된 응답 메시지에 트리거 정보가 함께 저장되어, 채팅을 다시 열었을 때 위쪽 작은 배너로 표시됩니다.

• 스케줄: 그 스케줄에 함께 저장된 프롬프트가 표시됩니다(스케줄 자체의 이름·실행 주기는 스케줄 서브페이지에서 확인).
• 웹훅: 요청 본문에 prompt 가 있었다면 그 문자열이 표시됩니다.
• 멘션: 보낸 에이전트 이름과 메시지 본문이 표시됩니다.

사용자가 직접 보낸 메시지(첫 번째 트리거)에서는 이 배너가 나타나지 않습니다.

트리거별 메타데이터 필드

자율 트리거로 실행된 응답 메시지에는 아래 필드들이 함께 저장되어 채팅 배너에 표시됩니다.

사용자가 직접 보낸 메시지(사용자 메시지 트리거)에는 이 메타데이터가 부착되지 않습니다.

더 알아보기

• 도구 부여하기 — 깨어난 에이전트가 어떤 도구를 쓸지 결정하기
• 스킬과 자율 스킬 시스템 — 반복 작업 절차를 스킬로 묶기
• 에이전트 공유 (스냅샷) — 외부 사용자에게 에이전트 노출하기