에이전트와 대화하기

Revka 에이전트와 대화하는 방법은 세 가지입니다. CLI (revka agent), 웹 대시보드의 오퍼레이터 채팅 어시스턴트, 그리고 연결된 메시징 채널 (Telegram, Discord, Slack, Matrix 등)입니다. 세 방식 모두 동일한 에이전트 루프, 메모리, 도구를 공유하며 — 차이는 입력하는 위치뿐입니다. 이 가이드에서는 각 인터페이스를 설명하고, 실제로 자주 사용하게 될 두 가지 기능인 대화 중 모델 전환과 응답 생성 중 조종도 함께 다룹니다.

호스트 프로세스를 아직 시작하지 않았다면, 게이트웨이 실행은 대시보드 실행하기를, 원격 채팅은 메시징 채널 연결하기를 참고하세요. 단일 턴이 처리되는 방식은 에이전트 루프를 참고하세요.

CLI에서 대화하기

revka agent는 에이전트와 직접 대화하는 가장 간단한 방법입니다. 데몬 없이 설정된 프로바이더와 모델을 대상으로 실행됩니다.

인터랙티브 모드 vs. 단발성 모드

• 인터랙티브 — 메시지 없이 revka agent를 실행하면 REPL 환경으로 진입합니다. 🦀 Revka Interactive Mode를 출력하고, 턴 간 대화 기록을 유지하며, 종료 전까지 세션을 유지합니다.
• 단발성 — -m/--message를 사용해 메시지 하나를 전송하고 응답을 출력한 뒤 종료합니다. 스크립트와 파이프라인에서 사용하기 적합한 형태입니다.

Interactive

revka agent
> Summarize today's logs
> /think:high Now draft a remediation plan
> /exit

Single-shot

revka agent -m "Summarize today's logs"
revka agent --provider anthropic --model claude-sonnet-4-20250514 -m "Status?"

주요 플래그:

플래그	설명
-m, --message <TEXT>	메시지 하나를 전송하고 종료 (단발성 모드)
--session-state-file <PATH>	대화 상태를 저장하고 복원할 JSON 파일
-p, --provider <ID>	이번 실행에 한해 기본 프로바이더를 재정의
--model <MODEL_ID>	이번 실행에 한해 기본 모델을 재정의
-t, --temperature <0.0-2.0>	온도를 재정의 ([0.0, 2.0] 범위의 float 값)
--peripheral <board:path>	하드웨어 주변 장치 연결 (반복 사용 가능), 예: nucleo-f401re:/dev/ttyACM0

플래그 대신 환경 변수로 기본값을 설정할 수도 있습니다. REVKA_PROVIDER, REVKA_MODEL, REVKA_TEMPERATURE, REVKA_API_KEY는 모두 해당 설정 키를 덮어씁니다. 전체 목록은 CLI 개요 및 환경 변수를 참고하세요.

참고

revka agent 실행 중에는 설정 핫 리로드가 지원되지 않습니다 — config.toml 변경 사항을 반영하려면 명령을 재시작해야 합니다. (장시간 실행되는 데몬과 채널은 프로바이더, 모델, 온도를 핫 리로드합니다. 채널에서 모델 전환하기를 참고하세요.)

인터랙티브 명령어

인터랙티브 세션 내에서 /로 시작하는 줄은 로컬에서 처리됩니다.

명령어	동작
/help	사용 가능한 인터랙티브 명령어 목록 표시
/clear, /new	대화를 초기화하고 세션 메모리 삭제 (y/N 확인 후 실행). 핵심 장기 메모리는 유지됩니다
/think:<level>	다음 턴의 추론 깊이 설정: off, minimal, low, medium, high, max
/quit, /exit	인터랙티브 모드 종료

/think:<level>은 일반 메시지 앞에 붙여 사용할 수도 있습니다. 예를 들어 /think:high Now draft a remediation plan은 해당 턴에만 추론 깊이를 높입니다.

--session-state-file로 상태 유지하기

기본적으로 인터랙티브 세션은 메모리에만 유지됩니다. --session-state-file <PATH>를 사용하면 세션을 영속적으로 저장할 수 있습니다.

revka agent --session-state-file ./session.json

• 시작 시 파일이 존재하면 Revka는 해당 파일의 history를 불러와 중단된 지점부터 이어서 진행하며, 시스템 프롬프트가 없는 경우 다시 삽입합니다. 파일이 없으면 새 세션으로 시작합니다.
• 파일은 의미 있는 턴 이후와 /new 실행 후 전체 메시지 목록을 담은 보기 좋게 포맷된 JSON으로 다시 작성됩니다.
• 동일한 경로가 메모리 세션 ID(cli:<path>)로 사용되므로, 대화는 Kumiho 메모리와도 연결됩니다.

이를 통해 오래 진행된 CLI 대화를 재개하거나, 실행 간에 트랜스크립트를 공유하거나, 스크립트 단발성 호출에 이전 컨텍스트를 제공할 수 있습니다. [heartbeat].load_session_context = true일 때 하트비트가 사용하는 파일도 이 파일이므로, 예약된 작업에서도 직접 메시지를 보낸 것처럼 최근 대화를 읽을 수 있습니다.

터미널 채널

채널 서브시스템을 통해 실행되는 의존성 없는 채팅 루프(agent REPL 대신)를 사용하려면, 설정에서 CLI 채널을 활성화하고 시작합니다.

[channels_config]
cli = true

revka channel start

/quit 또는 /exit를 입력하면 종료됩니다. 원격 채널을 연결하기 전에 에이전트를 간단히 테스트하기에 가장 좋은 방법입니다.

자연어로 모델 전환하기

모델 ID를 외울 필요가 없습니다. 인터랙티브 revka agent 세션이나 에이전트 루프에 연결된 채팅 인터페이스에서, 원하는 라우팅을 평범한 언어로 설명하면 에이전트가 내장된 model_routing_config 도구를 통해 적용합니다.

> set conversation to kimi and coding to gpt-5.3-codex

이 도구는 해당 지시에 따라 기본 모델, 시나리오별 라우팅, 위임 에이전트를 설정합니다. 설정 파일과 동일한 방식으로 라우팅을 수정하므로, 변경 사항은 현재 턴에만 적용되는 것이 아니라 에이전트에 지속됩니다. 모델을 확정적으로 고정하려면 위의 --provider/--model 플래그, revka models set 명령어, 또는 아래의 채널별 메시지 단위 명령어를 사용하세요. 전체 라우팅 모델은 설정: 프로바이더, 에이전트 및 라우팅과 라우팅, 안정성 및 튜닝을 참고하세요.

채널에서 모델 전환하기

Telegram, Discord, Slack, Matrix를 통해 대화할 때는 재시작이나 설정 수정 없이 채팅 내 명령어로 세션의 프로바이더와 모델을 전환할 수 있습니다. 이 네 채널은 런타임 모델 전환을 지원하며, /new는 모든 채널에서 작동합니다.

명령어	동작
/models	사용 가능한 프로바이더 목록 표시
/models <provider>	이 발신자의 세션에서 프로바이더 전환
/model	현재 모델 표시
/model <model-id>	이 세션의 모델 전환 (컨텍스트 유지)
/model <hint>	정확한 ID 대신 자연어 힌트로 모델 전환
/new	대화 기록 초기화 및 새 세션 시작

모델을 전환해도 대화 컨텍스트는 유지되며, /new만 기록을 초기화합니다. 봇 접미사가 붙어 있어도 인식되므로, 그룹 채팅에서 /models@yourbot 형태로도 작동합니다. 프로바이더 이름은 별칭을 허용하며, 알 수 없는 프로바이더를 입력하면 /models 실행을 안내하는 힌트가 반환됩니다.

한편 채널 런타임은 config.toml을 감시하여 재시작 없이 default_provider, default_model, default_temperature, 프로바이더의 api_key/api_url, reliability.*를 핫 리로드합니다. 따라서 설정 페이지나 디스크에서 수정한 내용은 다음 메시지부터 바로 적용됩니다. 자세한 내용은 revka channel 및 인테그레이션과 채널 개요를 참고하세요.

오퍼레이터 채팅 어시스턴트

대시보드에는 모든 페이지에서 사용할 수 있는 오퍼레이터 채팅 어시스턴트 플로팅 창이 내장되어 있습니다 (헤더의 어시스턴트 버튼으로 열 수 있습니다). 세 가지 탭 유형을 제공합니다.

• Chat — WebSocket 기반 실시간 오퍼레이터 세션. Markdown 렌더링, 파일 첨부, 인라인 도구 호출 활동 카드, 어시스턴트 메시지별 확장 가능한 트레이스를 지원합니다.
• Terminal — 내장 터미널. 각 내장 명령어가 게이트웨이 엔드포인트를 호출하고 JSON 결과를 렌더링합니다: status, cost, agents, config, sessions, health, integrations, clear, help.
• Code — 에이전트가 구동하는 코딩 세션으로, 출력을 구조화된 코드 블록으로 렌더링합니다.

Chat 탭은 WebSocket 세션으로 게이트웨이와 통신합니다.

ws[s]://<host>/ws/operator?session_id=<id>

세션은 영속적으로 저장되므로, 탭 이름을 바꾸고 (제목 더블클릭), 보관하거나 복원할 수 있습니다. 관련 REST 엔드포인트는 모두 기기 페어링을 통해 발급된 베어러 토큰이 필요합니다.

동작	메서드 + 경로	인증
세션 목록 조회	GET /api/sessions	Bearer
트랜스크립트 불러오기	GET /api/sessions/{id}/messages	Bearer
세션 이름 변경	PUT /api/sessions/{id} body { "name": "..." }	Bearer
세션 보관 / 삭제	DELETE /api/sessions/{id}	Bearer
첨부 파일 업로드	POST /api/sessions/{id}/attachments (multipart, 최대 25 MiB)	Bearer

Chat 탭 내에서 /를 입력하면 슬래시 명령어 팔레트가 열립니다. 기본 제공 명령어로는 /theme <name>, /new, /archive가 있습니다. 어시스턴트 인스턴스별로 색상 테마를 선택하고, 레이아웃 모드(팝아웃 컬럼, 분할, 하단 스트립)도 선택할 수 있습니다. 전체 참고 내용은 오퍼레이터 채팅 어시스턴트 페이지를 확인하세요.

응답 생성 중 조종하기

조종(steering) 기능은 에이전트가 응답을 생성하는 도중에 방향을 조정할 수 있게 해줍니다 — 완료될 때까지 기다렸다가 수정 메시지를 보낼 필요가 없습니다. 채팅 WebSocket(/ws/chat, /ws/operator)을 통해 작동합니다.

활성 턴 중에 steer 메시지를 전송합니다.

{ "type": "steer", "content": "Prefer the smaller fix" }

게이트웨이는 메모를 수락하고 operator_status 이벤트로 응답합니다.

{ "type": "operator_status", "phase": "steering", "detail": "Steering note accepted; it will apply at the next Operator boundary." }

알아두어야 할 규칙 몇 가지:

• 메모는 토큰 생성 도중이 아닌 다음 오퍼레이터 경계에서 적용됩니다. 이미 해당 경계를 지난 턴이라면, 현재 응답은 조종 시점을 지났다는 상태 메시지가 반환됩니다.
• 조종 텍스트는 세션 트랜스크립트에 사용자 메모로 추가되므로, 대화 기록의 일부가 됩니다.
• 빈 조종 내용은 거부되며(EMPTY_CONTENT), 활성 턴이 없을 때 조종 시도 시 No active Operator turn to steer (NO_ACTIVE_TURN)가 반환됩니다.

메시징 채널에서 조종에 해당하는 기능은 새 메시지 수신 시 인터럽트입니다. 활성화하면 첫 번째 응답이 완료되기 전에 두 번째 메시지를 보낼 경우, 해당 발신자의 진행 중인 생성이 취소됩니다. 채널별로 설정할 수 있습니다.

[channels_config.telegram]
interrupt_on_new_message = true

이 플래그는 Telegram, Slack, Discord, Mattermost, Matrix에서 사용할 수 있습니다. 위의 /model, /new 명령어와 함께 사용하면 원격 대화를 완전히 실시간으로 제어할 수 있습니다. 모든 인터페이스에서 완전히 중지하려면 긴급 정지 (revka estop)를 사용하세요.

다음 단계

revka agent 인터랙티브 및 단발성 에이전트 세션의 전체 플래그 참고 자료.

오퍼레이터 채팅 어시스턴트 Chat, 터미널, 코드 탭, 슬래시 명령어, 레이아웃 모드.

메시징 채널 연결하기 Telegram, Discord, Slack 등을 연결해 어디서나 대화하기.

세션 및 대화 상태 Revka가 턴과 인터페이스 전반에 걸쳐 메모리와 상태를 관리하는 방식.