커뮤니케이션 및 에스컬레이션 도구

이 페이지는 Revka 에이전트가 사람 및 다른 세션과 통신하는 데 사용하는 에이전트 도구를 설명합니다: 메시지에 반응 추가, 질문 후 응답 대기, 사람에게 에스컬레이션, 투표 실행, Pushover 푸시 알림 발송, 그리고 대화 세션 간의 읽기/쓰기 기능을 포함합니다. 각 도구가 허용하는 정확한 파라미터를 확인할 때 이 페이지를 참조하세요.

도구는 세 가지 그룹으로 나뉩니다:

• 채널 상호작용 — reaction, ask_user, escalate_to_human, poll은 실시간 메시징 채널로 무언가를 전송합니다. 이 도구들은 시작 시 적어도 하나의 채널이 구성되고 초기화되어 있어야 합니다. 채널 개요 및 메시징 채널 연결을 참조하세요.
• 푸시 알림 — pushover (및 escalate_to_human의 에스컬레이션 경로)는 Pushover를 통해 모바일 푸시를 발송합니다.
• 세션 간 메시징 — sessions_list, sessions_history, sessions_send는 다른 대화 세션을 조회하고 기록하여 세션 간 및 에이전트 간 통신을 가능하게 합니다. 세션 및 대화 상태를 참조하세요.

참고

채널 도구(reaction, ask_user, escalate_to_human, poll)는 채널이 부팅된 후 Revka가 채워 넣는 실시간 채널 맵을 참조합니다. 채널이 초기화되기 전까지는 No channels available yet (channels not initialized)를 반환합니다. 이 도구들은 모두 보안 정책의 적용을 받으며 읽기 전용 자율성 모드에서는 차단됩니다. 자율성 수준 및 승인을 참조하세요.

채널 상호작용 도구

reaction

활성 채널(Discord, Slack, Telegram 등)의 메시지에 이모지 반응을 추가하거나 제거합니다. 메시지는 Revka의 내부 채널 이름이 아닌 플랫폼 채널 ID와 메시지 ID로 식별합니다.

{
  "channel": "discord",
  "channel_id": "123456789",
  "message_id": "msg_123",
  "emoji": "👍",
  "action": "add"
}

필드	타입	설명
channel	string (필수)	반응을 추가할 구성된 채널 이름 (예: discord, slack, telegram).
channel_id	string (필수)	플랫폼별 채널/대화 식별자 (예: Discord 채널 스노우플레이크, Slack 채널 ID).
message_id	string (필수)	반응을 추가할 메시지의 플랫폼 범위 식별자.
emoji	string (필수)	이모지 — 유니코드 문자(예: 👍) 또는 플랫폼 단축코드.
action	string	add(기본값) 또는 remove. 그 외 값은 거부됩니다.

지정한 채널이 채널 맵에 없으면 도구의 오류 메시지에 사용 가능한 채널 이름이 표시됩니다. 이모지 형식은 플랫폼마다 다릅니다 — 유니코드 문자를 기대하는 플랫폼도 있고 단축코드를 기대하는 플랫폼도 있으므로, 대상 플랫폼이 허용하는 형식을 사용하세요.

ask_user

메시징 채널에서 사용자에게 질문을 하고 응답이 오거나 타임아웃이 만료될 때까지 에이전트 루프를 차단합니다. choices를 전달하면 구조화된 선택지를 제공할 수 있으며, CLI에서는 번호 목록으로, Telegram 같이 지원하는 플랫폼에서는 버튼으로 렌더링됩니다.

{
  "question": "Which deployment environment should I use?",
  "choices": ["production", "staging", "dev"],
  "timeout_secs": 120
}

필드	타입	설명
question	string (필수)	질문 내용. 비어 있으면 안 됩니다.
choices	array of strings	선택적 구조화 옵션. 번호 목록(지원 채널에서는 버튼)으로 렌더링됩니다. 빈 항목은 제거됩니다.
timeout_secs	integer	응답 대기 시간(초). 기본값 300.
channel	string	대상 채널 이름. 생략 시 첫 번째 사용 가능한 채널로 기본 설정됩니다.

도구는 성공 시 사용자의 응답 텍스트를 반환합니다. 타임아웃 시 success: false와 함께 TIMEOUT 출력 및 No response received within 120 seconds 같은 오류를 반환합니다. 존재하지 않는 채널을 지정하면 오류에 사용 가능한 채널 목록이 표시됩니다.

주의

ask_user는 응답을 기다리는 동안 전체 timeout_secs 시간 동안 에이전트 루프를 열어 둡니다. 인터랙티브 흐름에서는 타임아웃을 짧게 유지하고, 결정론적으로 파싱할 수 있는 답변을 원할 때는 choices를 사용하세요.

escalate_to_human

긴급도 라우팅을 통해 상황을 사람 운영자에게 에스컬레이션합니다. 활성 채널에 긴급도 접두사가 붙은 구조화된 메시지를 전송하며, high 또는 critical 긴급도의 경우 자격 증명이 구성되어 있으면 Pushover 알림도 발송합니다. 선택적으로 사람의 응답을 기다리며 차단할 수 있습니다.

{
  "summary": "Database replication lag exceeded 30s",
  "context": "Lag has been growing for 10 minutes",
  "urgency": "high",
  "wait_for_response": true,
  "timeout_secs": 600
}

필드	타입	설명
summary	string (필수)	에스컬레이션 요약(한 줄). 비어 있으면 안 됩니다.
context	string	사람을 위한 상세 컨텍스트.
urgency	string	low, medium(기본값), high, critical. 그 외 값은 거부됩니다.
wait_for_response	boolean	기본값 false. true이면 도구가 차단되고 사람의 응답을 반환합니다.
timeout_secs	integer	wait_for_response가 true일 때의 대기 타임아웃. 기본값 600.

에스컬레이션은 첫 번째 사용 가능한 채널로 전송됩니다. 메시지는 긴급도 접두사 — ℹ️ [LOW], ⚠️ [MEDIUM], 🔴 [HIGH], 🚨 [CRITICAL] — 에 이어 요약, 선택적 컨텍스트, Reply to this message to respond. 줄이 붙습니다.

wait_for_response가 false이면 도구는 즉시 JSON 상태를 반환합니다(예: {"status":"escalated","urgency":"high","channel":"slack"}). true이면 사람의 응답 텍스트를 반환하거나, 시간 내 응답이 없으면 TIMEOUT을 반환합니다.

Pushover 단계는 최선 노력(best-effort) 방식입니다: Pushover 자격 증명이 없거나 푸시가 실패해도 high/critical 에스컬레이션은 채널 전송만으로 성공 처리됩니다. 푸시 제목은 Agent Escalation이며, Pushover 우선순위는 critical이 1, high가 0입니다. low와 medium은 푸시를 발송하지 않습니다.

팁

질문에 대한 답변을 기대할 때는 ask_user를 사용하고, 사람의 주의가 필요한 긴급 알림(선택적으로 확인 응답 포함)에는 escalate_to_human을 사용하세요. 긴급도 라우팅과 자동 Pushover 전달은 escalate_to_human에서만 제공됩니다.

poll

메시징 채널에 투표를 생성합니다. 투표는 숫자 이모지(1️⃣–🔟) 투표 방식의 번호 텍스트 메시지로 렌더링되므로 모든 채널에서 작동합니다.

{
  "question": "Which tech talk topic should we host next?",
  "options": ["Rust", "WebAssembly", "AI agents"],
  "channel": "discord",
  "duration_minutes": 60,
  "multi_select": false
}

필드	타입	설명
question	string (필수)	투표 질문. 비어 있으면 안 됩니다.
options	array of strings (필수)	답변 선택지. 2–10개의 비어 있지 않은 항목; 이 범위를 벗어나면 호출이 거부됩니다.
channel	string	대상 채널 이름. 생략 시 첫 번째 사용 가능한 채널로 기본 설정됩니다.
recipient	string	채널 내 수신자/채팅 식별자 (예: Telegram 채팅 ID 또는 Slack 채널 ID).
duration_minutes	integer	메시지에 표시되는 투표 기간. 기본값 60.
multi_select	boolean	기본값 false. “단일 선택” 또는 “복수 선택 허용” 레이블을 제어합니다.

참고

Telegram과 Discord는 네이티브 투표 지원 플랫폼으로 감지되지만, 현재 채널 인터페이스는 모든 채널에 텍스트 형식 투표를 전달합니다 — 네이티브 투표 API는 아직 연결되어 있지 않으므로 도구는 플랫폼 네이티브 투표를 생성하는 대신 출력에 의도를 기록합니다. 투표는 숫자 이모지 반응을 통해 이루어지며, 도구는 결과를 집계하거나 반환하지 않습니다 — 결과는 채널에서 확인할 수 있습니다.

푸시 알림

pushover

구성된 기기로 Pushover 푸시 알림을 발송합니다. 자격 증명은 에이전트의 워크스페이스 디렉토리에 있는 .env 파일에서 읽어옵니다.

{
  "message": "Deployment succeeded",
  "title": "CI/CD",
  "priority": 1
}

필드	타입	설명
message	string (필수)	알림 본문. 비어 있으면 안 됩니다.
title	string	선택적 알림 제목.
priority	integer	-2(최저/무음), -1(낮음/무음), 0(보통), 1(높음), 2(긴급/반복). -2..=2 범위를 벗어나면 거부됩니다.
sound	string	알림 소리 재정의 (예: pushover, bike, bugle, cashregister).

설정: Pushover 계정과 애플리케이션을 생성하여 API 토큰을 발급받은 후, 워크스페이스의 .env 파일에 두 값을 추가합니다:

# .env (in the agent's workspace directory)
PUSHOVER_TOKEN=your-application-api-token
PUSHOVER_USER_KEY=your-user-key

두 키 모두 필수이며, 하나라도 없으면 도구가 오류를 반환합니다. export 접두사, 따옴표로 감싼 값, 후행 # comments는 허용됩니다. 우선순위 2(긴급)는 Pushover 앱에서 확인할 때까지 반복 발송됩니다.

참고

escalate_to_human은 high/critical 긴급도에 대해 Pushover를 자동으로 호출하므로, 에스컬레이션 시 별도의 pushover 호출은 필요하지 않습니다. 에스컬레이션이 아닌 독립적인 알림에는 pushover를 직접 사용하세요.

세션 간 메시징

이 세 가지 도구를 사용하면 에이전트가 다른 대화 세션을 조회하고 작업할 수 있습니다. 세션은 <channel>__<identifier> 형태의 키로 식별됩니다(예: telegram__alice 또는 discord__bob). __ 앞 부분이 채널입니다. 세션은 워크스페이스의 세션 백엔드에 영속됩니다.

sessions_list는 읽기 전용이며 게이팅 없이 사용할 수 있습니다. sessions_history는 Read 도구 작업이 필요하고, sessions_send는 Act 작업이 필요하므로 두 도구 모두 보안 정책의 적용을 받습니다. session_id는 비어 있으면 안 되며 적어도 하나의 영숫자 문자를 포함해야 합니다.

sessions_list

활성 세션을 채널, 마지막 활동 시간, 메시지 수와 함께 나열합니다.

{"limit": 20}

필드	타입	설명
limit	integer	반환할 최대 세션 수. 기본값 50.

세션이 없으면 No active sessions found.를 반환합니다. 있으면 - telegram__alice: channel=telegram, messages=2, last_activity=... 형식으로 세션당 한 줄씩 반환합니다.

sessions_history

특정 세션의 메시지 기록을 읽어 최근 N개의 메시지와 역할을 반환합니다.

{"session_id": "telegram__alice", "limit": 50}

필드	타입	설명
session_id	string (필수)	세션 ID (예: telegram__alice). sessions_list에서 확인합니다.
limit	integer	가장 최근 메시지부터 반환할 최대 메시지 수. 기본값 20.

각 메시지는 Session 'telegram__alice': showing 2/2 messages와 같은 헤더 다음에 [<role>] <content> 형식으로 렌더링됩니다(user, assistant 등의 역할 포함). 알 수 없거나 빈 세션은 No messages found for session '...'.을 반환합니다.

sessions_send

ID로 특정 세션에 메시지를 전송합니다. 메시지는 해당 세션의 대화 기록에 user 메시지로 추가됩니다 — 이것이 에이전트 간 통신을 가능하게 하는 푸시 모델입니다: 대상 세션이 다음에 실행될 때 해당 메시지가 기록에 포함되어 에이전트의 응답을 유도합니다.

{
  "session_id": "discord__bob",
  "message": "The background task has completed. Results: ..."
}

필드	타입	설명
session_id	string (필수)	대상 세션 ID (예: discord__bob).
message	string (필수)	메시지 내용. 비어 있으면 안 됩니다.

성공 시 Message sent to session '<id>'.를 반환합니다. 존재하지 않는 세션 ID로 전송하면 백엔드에 해당 키를 생성/추가합니다. 유효성 검사는 비어 있거나 영숫자가 없는 ID와 빈 메시지만 거부합니다.

주의

sessions_send는 해당 채널의 일반 수신 경로를 거치지 않고 다른 세션의 기록에 직접 씁니다. 이를 자신의 에이전트 간 내부 조정 수단으로 취급하세요 — 플랫폼의 임의 사용자에게 메시지를 보내려면 채널을 통해 전송하거나 cron_add로 예약 전달을 설정하세요.

관련 페이지

• 도구 개요 — 도구 등록 및 게이팅 방식.
• 채널 개요 및 메시징 채널 연결 — 이 도구들이 사용하는 채널 설정 방법.
• 세션 및 대화 상태 — sessions_* 도구의 기반이 되는 세션 모델.
• 자율성 수준 및 승인 — 읽기 전용 자율성 모드에서 이 도구들이 차단되는 이유.
• 스케줄링 및 SOP 도구 — 예약된 채널 메시지를 위한 cron_add 전달.
• 에이전트 생성 및 조정 — 세션 간 메시징을 기반으로 하는 멀티 에이전트 패턴.