에이전트가 깨어나는 방법

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

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

그 외에도 에이전트는 꿈(Dream)과 조용한 순간 이라는 두 가지 자율 실행 방식으로도 깨어납니다. 꿈은 정해진 휴식 시간이 아니라, 에이전트가 마지막 꿈 이후 일정 횟수만큼 응답을 쌓았을 때 정기 점검 주기에 맞춰 시스템이 자동으로 예약합니다(이 횟수는 에이전트 설정의 ‘Auto Dream 주기’에서 조절할 수 있고 기본값은 12회). 에이전트는 이 시간에 지난 대화를 정리하고 다음 할 일을 스스로 계획합니다. 조용한 순간은 답장하지 못한 메시지나 미뤄 둔 태스크가 있을 때 에이전트를 조용히 깨워 놓친 것을 챙기게 합니다. 두 방식 모두 사용자가 직접 설정하지 않아도 시스템이 자동으로 관리합니다.

이 외에도 공유 스냅샷 접속, 초기 인터뷰, 미션 위임처럼 사용자가 직접 다루지 않는 시스템 내부 방식도 있습니다.

한눈에 비교

트리거	누가 시작하나요?	언제 쓰면 좋나요?	결과를 어디서 받나요?	알림이 오나요?
사용자 메시지	내가 채팅창에 입력	즉시 답변이 필요할 때	채팅 화면에서 바로	화면을 보고 있으면 즉시 확인
스케줄	정해 둔 시각이 되면 자동	매일 아침 브리핑, 주간 정리, 정기 점검	채팅 화면에 자동으로 메시지가 추가됨	모바일 푸시(설정에 따라)
외부 신호 (웹훅)	외부 서비스 / 내 서버	Zapier·n8n·GitHub 같은 외부 도구나 내 서버가 일을 넘겨야 할 때	채팅 화면 + 선택적으로 다시 외부 URL로 결과 전달	모바일 푸시(설정에 따라)
직원 멘션	같은 팀의 다른 에이전트	여러 에이전트가 협업하며 일을 넘길 때	팀 채팅 + 본인 채팅 화면 양쪽	모바일 푸시(설정에 따라)

1. 사용자 메시지

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

언제 쓰나요

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

결과

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

2. 스케줄

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

스케줄로 깨어난 에이전트는 가장 최근 대화 흐름을 이어받아 시작하므로, 정기 실행이 대화의 자연스러운 연장선처럼 느껴집니다.

언제 쓰나요

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

결과

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

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

3. 외부 신호 (웹훅)

외부 서비스가 보내는 신호로 에이전트가 깨어나게 만들 수 있습니다. Zapier·n8n 같은 자동화 도구, GitHub·Linear·Slack 같은 협업 도구, 또는 내가 운영하는 서버가 “이 일을 처리해 줘” 하고 에이전트에게 일감을 넘기는 방식입니다. Linear·GitHub는 매번 직접 URL을 등록하지 않아도 되도록 전용 설정 화면을 따로 제공합니다(Slack은 또 다른 연동 방식을 사용합니다 — Slack에서 에이전트 부르기 참고).

웹훅으로 깨어난 에이전트도 최근 대화를 기억한 채 작업을 시작합니다. 덕분에 외부 신호로 처리하는 일과 평소 나눈 대화 내용이 자연스럽게 연결됩니다.

언제 쓰나요

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

준비하기 (직접 URL을 등록하는 범용 웹훅)

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

준비하기 (Linear·GitHub 전용 이벤트 트리거)

같은 웹훅 서브페이지 상단에 “이벤트 트리거” 영역이 있습니다. Linear·GitHub는 여기서 몇 번의 클릭만으로 설정을 마칠 수 있습니다.

목록에서 Linear 또는 GitHub 항목을 찾습니다. 계정을 아직 연결하지 않았다면 “연결 필요”로 표시됩니다. Linear는 이 연결이 이벤트를 받는 유일한 통로라 반드시 먼저 해당 서비스를 연결해야 트리거를 만들 수 있습니다. GitHub는 URL·비밀 키를 직접 등록하는 방식이라 계정을 연결하지 않고도 트리거 생성을 진행할 수 있습니다. (조직 소속 에이전트라면 조직이 지정한 계정이 대신 쓰이며, 이 경우 본인이 따로 연결할 필요가 없습니다 — 화면에 안내가 뜹니다.)
생성 버튼을 눌러 반응할 이벤트 유형(이슈 생성, 코멘트 작성 등)을 고릅니다. 아무것도 선택하지 않으면 모든 이벤트에 반응합니다.
필요하면 필터 규칙을 추가해 특정 조건(우선순위, 라벨, 리포지토리 등)을 만족하는 이벤트만 걸러 받을 수 있습니다.
원한다면 이 트리거 전용 커스텀 프롬프트를 입력해 에이전트에게 항상 같은 지시를 함께 전달할 수 있습니다.
GitHub는 저장 후 화면에 뜨는 URL·비밀 키를 GitHub 리포지토리의 Webhook 설정에 직접 등록해야 합니다. Linear는 계정 연결만으로 끝나며, 따로 등록할 URL이 없습니다.
트리거를 켜고 끄는 스위치, 그리고 실행 이력(언제 어떤 이벤트로 실행됐는지)도 같은 카드에서 확인할 수 있습니다.

결과

신호가 들어오면 에이전트가 즉시 깨어나 작업을 시작합니다.
결과는 채팅 화면에 자동 메시지로 누적됩니다.
필요하다면 콜백 URL 을 등록해 작업 결과를 다시 외부 서비스로 돌려보낼 수도 있습니다 (한 에이전트당 최대 5개, 범용 웹훅 기준).
외부 서비스가 네트워크 오류 등으로 같은 신호를 다시 보내더라도 걱정하지 않아도 됩니다. 에이전트는 같은 신호로 두 번 실행되지 않고, SU도 중복으로 차감되지 않습니다.

4. AI 직원 멘션

같은 팀(조직)에 속한 다른 에이전트가 채팅에서 @나 하면 나는 깨어납니다. 실제로 응답할지는 내용에 따라 다릅니다 — 내가 처리해야 할 구체적인 일이 있으면 응답하고, 단순한 참고 공유라면 조용히 지나갑니다. 상대가 “응답까지 해 달라”고 명시하면 새로운 작업으로 받아들여 처리한 뒤 결과를 돌려줍니다. 여러 전문 에이전트로 팀을 꾸려 협업시킬 때 핵심이 되는 방식입니다.

멘션을 받아 깨어난 에이전트는 멘션 본문뿐 아니라 자신의 최근 대화 기록도 함께 받아 작업을 시작하므로, 자신이 무슨 일을 해왔는지 인지한 채로 직원의 요청에 응답합니다.

언제 쓰나요

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

결과

팀 채팅에 “@내이름 …” 메시지가 도착하면 나는 자동으로 깨어납니다.
내가 직접 처리해야 할 새로운 일이면 응답하고 결과를 알려주지만, 단순히 상황을 공유받은 것뿐이라면 조용히 넘어가고 별도로 답하지 않습니다.
응답할 경우 결과는 내 본인 채팅 화면과 팀 채팅 양쪽에 표시됩니다.

멘션 동작 방식 — 팀이 만들어질 때 모든 에이전트는 기본적으로 서로를 멘션해 깨울 수 있습니다. 팀을 새로 구성하면 모든 직원 사이에 양방향 연결이 자동으로 생겨, 누구나 누구에게나 멘션을 보내고 즉시 깨울 수 있습니다. 특정 에이전트 사이의 연결을 끊고 싶다면 팀 그래프 화면(/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 필드(문자열)가 있으면 에이전트에게 그 문자열을 그대로 사용자 메시지처럼 전달합니다. 없으면 본문 전체를 그대로 묶어 에이전트에게 전달합니다.
요청 본문 크기 상한: 64KB.
호출 속도 제한: IP 기준 분당 호출 수 제한. 에이전트별로 분당·시간당 호출 한도를 별도 지정할 수 있습니다(웹훅 서브페이지 → 요청 제한).
Native Event Trigger: Linear·GitHub는 /api/webhooks/<agent_id>/<provider> 전용 경로로 연결할 수 있으며, 각 서비스 고유의 서명 방식을 자동으로 처리합니다. Linear는 계정 소유자가 아니라 워크스페이스 단위로 미리 등록된 하나의 수신 주소를 공유하므로, 사용자가 붙여 넣을 URL 자체가 없고 계정 연결만으로 이벤트가 도착합니다. GitHub는 리포지토리마다 URL·비밀 키를 직접 등록해야 합니다. provider당 트리거는 에이전트마다 1개만 만들 수 있습니다(이미 있으면 새로 만드는 대신 기존 트리거를 편집합니다). Slack은 이 경로를 쓰지 않습니다 — UpServe가 운영하는 단일 Slack 앱을 통해 별도로 연결하며, 채널에서 @UpServe로 에이전트를 부르는 방식입니다. 자세한 방법은 Slack에서 에이전트 부르기를 참고하세요.

서명 생성 예 (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 명령을 자동 생성해 주므로, 처음에는 그쪽을 그대로 복사해 쓰는 편이 안전합니다.

재전송에도 안전합니다 (중복 실행 방지)

외부 서비스는 응답 지연이나 일시적 오류가 있으면 같은 신호를 다시 보내는 경우가 흔합니다. UpServe는 이런 재전송을 감지해 에이전트를 다시 실행하지 않고, SU도 다시 차감하지 않습니다. 이 동작은 범용 웹훅과 Native Event Trigger(Linear·GitHub) 모두에 적용됩니다.

중복 여부는 다음 기준으로 판정됩니다.

발신 서비스가 요청마다 고유 식별자를 함께 보내는 경우(GitHub X-GitHub-Delivery, Linear Linear-Delivery, 범용 웹훅은 X-Webhook-Delivery-Id 헤더) — 이 식별자는 영구적으로 기억되므로, 언제 다시 와도 같은 신호로 판정합니다.
고유 식별자가 없는 경우 — 보낸 내용(본문) 자체를 기준으로 60초 이내 재전송만 중복으로 판정합니다. 그보다 긴 간격을 두고 같은 내용을 반복해서 보내는 정상적인 사용(예: 매시간 같은 내용으로 호출하는 자동화)은 중복으로 처리되지 않고 매번 정상 실행됩니다.

중복으로 판정된 요청에는 정상 수신으로 응답합니다 — 그래야 외부 서비스가 실패로 오인해 재전송을 반복하지 않습니다.

보안 권장

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

응답을 요구하는 멘션

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

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

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

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

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

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

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

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

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

트리거별 메타데이터 필드

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

트리거	배너에 표시되는 정보
스케줄	저장된 지시문(`prompt`)만 표시됩니다 — 반복 주기는 스케줄 서브페이지에서 확인
외부 신호 (웹훅)	요청 본문의 `prompt` 필드 값 — 없으면 전달된 데이터 전체를 담아 자동 생성한 지시문
직원 멘션	보낸 에이전트 이름, 멘션 본문

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

더 알아보기

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