에이전트 생성 및 조정
create_agent, 생명주기 도구, 에이전트 템플릿, 목표, 계획, 세션, 결과 기록, 권한/정책 제어.
Operator MCP는 Revka의 오케스트레이션 핵심 모듈입니다. 에이전트가 하위 에이전트 서브프로세스를 생성하고, 생명주기를 관리하며, 표준화된 에이전트 템플릿을 재사용하고, 목표와 계획을 추적하고, 세션을 저널링 및 아카이빙하고, 결과를 기록하고, 긴 대화를 압축하고, 실행 전에 권한 및 자율성 정책을 적용할 수 있도록 MCP 도구 집합을 제공합니다.
이 페이지에서는 해당 오케스트레이션 기본 요소들을 MCP 도구 형태로 설명합니다. 한 에이전트가 다른 에이전트들을 조율해야 할 때 — 코더 + 리뷰어 루프, 리서치 팬아웃, 또는 학습 내용을 기억해야 하는 장기 실행 작업 — 이 페이지를 참고하세요. 이 기본 요소들 위에 구축된 더 높은 수준의 구조에 대해서는 에이전트, 팀 & 스웜 및 대시보드의 에이전트, 팀 & 캔버스 페이지를 참조하세요.
create_agent로 에이전트 생성
섹션 제목: “create_agent로 에이전트 생성”create_agent는 새로운 코딩 에이전트 서브프로세스를 생성합니다. 지원되는 다섯 가지 CLI 백엔드 중 하나를 실행하고, 선택적으로 에이전트 템플릿을 상속하며, 에이전트를 특정 도구 허용 목록으로 제한하고, 빌드/테스트 작업을 위해 정리된 환경에서 실행할 수 있습니다.
{ "title": "rust-coder", "cwd": "/home/user/myproject", "agent_type": "codex", "initial_prompt": "Implement the auth module", "template": "rust-coder", "model": "claude-opus-4-5", "allowed_tools": ["Read", "Edit", "Bash"], "max_turns": 100, "parent_id": "<uuid>", "clean_build": true}| 파라미터 | 타입 | 필수 | 의미 |
|---|---|---|---|
title | string | 예 | 에이전트의 짧은 레이블 (최대 60자). |
cwd | string | 예 | 절대 경로의 작업 디렉터리. 템플릿 사용 시에도 항상 명시적으로 전달하세요. |
agent_type | enum | 아니오 | CLI 백엔드: claude, codex, agy, agent, 또는 opencode. 템플릿의 타입을 재정의합니다. |
initial_prompt | string | 아니오 | 생성 시 전송되는 프롬프트. |
template | string | 아니오 | 풀 템플릿 이름. agent_type, default_cwd, system_hint를 상속합니다. |
model | string | 아니오 | 모델 선택을 지원하는 CLI를 위한 모델 힌트. |
allowed_tools | string[] | 아니오 | 도구 허용 목록. 생략하면 모든 도구가 허용됩니다. |
max_turns | integer | 아니오 | 자동 중지 전 최대 대화 턴 수. 기본값 200. |
parent_id | string | 아니오 | 계층적 생성 및 캐시 안전 프롬프트 재사용을 위한 부모 에이전트 UUID. |
clean_build | boolean | 아니오 | 정리된 환경 사용 (엄격한 변수 허용 목록, 빌드 캐시 초기화). 기본값 false. 빌드/테스트 에이전트에 권장됩니다. |
node_env | string | 아니오 | 에이전트 프로세스의 NODE_ENV. 기본값 development. |
에이전트는 응답에 반환된 UUID로 식별됩니다. 아래의 모든 생명주기 도구에서 해당 UUID를 사용하세요.
에이전트 생명주기 도구
섹션 제목: “에이전트 생명주기 도구”에이전트가 실행 중이면, 아래 도구들로 대기, 후속 프롬프트 전송, 검사, 취소, 정리 등 생명주기 전반을 제어할 수 있습니다.
| 도구 | 기능 |
|---|---|
wait_for_agent(agent_id, timeout?) | 에이전트가 완료될 때까지 블로킹합니다. 기본 타임아웃 120s. |
send_agent_prompt(agent_id, prompt) | 유휴 또는 완료된 에이전트에 후속 프롬프트를 전송합니다. |
get_agent_activity(agent_id) | 상태, 도구 호출 수, 오류 수, 수정된 파일, 마지막 실패 명령, 사용 통계 등의 구조화된 요약을 반환합니다. |
get_agent_run_log(agent_id, view?, limit?) | 상세 실행 로그. view: summary (기본값), tool_calls, errors, files, full. limit 기본값 50. 실행 중 및 완료된 에이전트 모두 지원합니다. |
list_agents() | 관리 중인 모든 에이전트의 ID, 사이드카 ID, 백엔드, 제목, 상태, cwd 등 메타데이터를 반환합니다. |
list_run_logs() | 디스크에서 사용 가능한 모든 실행 로그를 반환합니다. |
get_agent_health(agent_id?) | 하트비트 / 생존 여부 정보. 중단된 에이전트를 감지합니다. agent_id를 생략하면 모든 에이전트를 대상으로 합니다. |
diff_agent_artifacts(agent_a, agent_b) | 두 에이전트의 수정 파일, 출력 유사도, 도구 호출 패턴, 오류 차이를 비교합니다. |
get_workflow_context(view?, agent_id?, status_filter?) | 이 세션에서 완료된 에이전트들의 누적된 결과물을 반환합니다. view: summary, findings, finding. |
cancel_agent(agent_id) | 실행 중인 에이전트를 취소합니다. 서브프로세스는 SIGINT → SIGTERM → SIGKILL 순으로 점진적 시그널을 사용하며, 사이드카 에이전트는 인터럽트 + 종료를 사용합니다. |
cancel_all_agents() | 실행 중인 모든 에이전트를 취소하고 에이전트별 결과를 반환합니다. |
prune_completed_agents(older_than_seconds?, include_idle?, include_cancelled?, include_failed?, dry_run?) | 실행 로그와 워크플로우 이력은 보존하면서 비활성 런타임 레코드를 제거합니다. older_than_seconds 기본값 60; include 플래그 기본값 true. |
에이전트 템플릿 풀
섹션 제목: “에이전트 템플릿 풀”템플릿 풀은 Kumiho의 <harness>/AgentPool/ 하위에 저장된 재사용 가능한 에이전트 정의의 영구 레지스트리입니다. 각 템플릿은 에이전트의 타입, 역할, 역량, 정체성, 성향, 톤, 선호 모델, 기본 작업 디렉터리를 저장하므로, create_agent와 오케스트레이션 패턴이 이름으로 표준화된 에이전트를 인스턴스화할 수 있습니다.
| 도구 | 기능 |
|---|---|
search_agent_pool(query) | 이름, 역할, 역량, 설명에 대한 키워드 검색. |
save_agent_template(name, agent_type, role, capabilities, description, identity?, soul?, tone?, default_cwd?, system_hint?, model?) | 템플릿을 생성하거나 업데이트합니다. |
list_agent_templates() | 모든 템플릿을 사용 횟수 순으로 정렬하여 반환합니다. |
get_agent_trust(template_name?) | 템플릿의 신뢰 점수: 성공률, 총 실행 횟수, 최근 결과. template_name을 생략하면 점수가 있는 모든 템플릿을 반환합니다. |
{ "name": "rust-coder", "agent_type": "codex", "role": "coder", "capabilities": ["rust", "testing"], "description": "Senior Rust engineer for systems work.", "identity": "Senior Rust engineer with 10+ years of systems experience.", "soul": "Correctness first, performance second.", "tone": "Technical, direct, precise.", "model": "claude-opus-4-5"}- **
role**은coder,reviewer,researcher,tester,architect,planner중 하나입니다. - **
agent_type**은claude,codex,agy,agent,opencode중 하나입니다. - 사용 횟수는 템플릿이 사용될 때마다 자동으로 추적되며, 이 때문에
list_agent_templates()가 사용 횟수 기준으로 정렬됩니다.
신뢰 점수는 결과를 기록할 때마다 누적됩니다(결과 기록 참조). 패턴 선택에 활용되며, 예를 들어 정제 루프는 템플릿의 신뢰 점수가 0.7 미만으로 떨어지면 비평자를 자동으로 교체합니다.
목표 계층 구조
섹션 제목: “목표 계층 구조”목표는 Kumiho의 Revka/Goals/ 하위에 계층 구조로 추적됩니다. 목표는 parent_kref를 통해 트리 구조(전략적 → 전술적 → 작업 수준)를 형성하며, 각각 상태와 우선순위를 가집니다.
| 도구 | 기능 |
|---|---|
create_goal(name, description, status?, priority?, parent_kref?) | 목표를 생성합니다. status 기본값 active; priority 기본값 p1. |
get_goals(status?, priority?) | 목표를 반환합니다. 선택적으로 상태 또는 우선순위로 필터링할 수 있습니다. |
update_goal(kref, status?, priority?, description?) | 목표의 필드를 업데이트합니다. |
status:active,completed,blocked,deferred.priority:p0,p1,p2,p3.p0/p1은 장기적 전략 목표로,p2/p3는 작업 수준 항목으로 취급하세요.parent_kref를 전달하면 부모 아래에 하위 목표를 중첩할 수 있습니다.
실행 계획 및 회상
섹션 제목: “실행 계획 및 회상”계획은 복잡한 작업의 분해 방식을 기록하는 영구 레코드로, Kumiho의 Revka/Plans/ 하위에 저장됩니다. 새로운 작업을 분해하기 전에 유사한 과거 계획을 회상하는 것이 operator의 주요 학습 메커니즘입니다.
| 도구 | 기능 |
|---|---|
save_plan(name, task_description, steps, agents_used?, outcome, lessons?) | 계획을 단계, 에이전트, 결과와 함께 저장합니다. outcome: success, partial, failed. |
recall_plans(query) | 작업 설명을 기준으로 과거 계획을 시맨틱 검색합니다. |
세션 저널 및 아카이빙
섹션 제목: “세션 저널 및 아카이빙”operator는 ~/.revka/operator_mcp/session.ndjson에 에이전트 생명주기 이벤트의 로컬 NDJSON 저널을 유지하며, 세션당 하나의 레코드 스트림을 기록합니다. 중요한 세션은 장기 회상을 위해 Kumiho의 Revka/Sessions/ 하위에 아카이빙할 수 있습니다.
| 도구 | 기능 |
|---|---|
get_session_history(session_id?, agent_id?, limit?, list_sessions?) | 저널에서 과거 세션 및 생명주기 이벤트를 회상합니다. limit 기본값 30. list_sessions: true로 설정하면 세션별 요약을 반환합니다. |
archive_session(title, summary, outcome, session_id?) | 완료된 세션을 Kumiho에 아카이빙합니다. outcome: success, partial, failed. session_id 기본값은 현재 세션입니다. |
get_journal_health() | 저널 크기, 쓰기 지연 시간, 순환 상태를 반환합니다. 데이터 손실이 발생하기 전에 디스크 문제를 감지합니다. |
각 에이전트 채팅 세션은 새로운 session_id로 새 operator 프로세스를 시작하므로, get_session_history는 재시작 후 컨텍스트를 복원하는 방법입니다. 중요한 멀티 에이전트 작업 후에는 archive_session을 호출하여 조직 메모리를 구축하세요.
결과 기록
섹션 제목: “결과 기록”결과(Outcome)는 에이전트(또는 스킬)가 발견하거나 결정한 내용을 기록하는 추가 전용 메모리입니다. <harness>/Sessions/<session_id>/Outcomes/ 하위에 세션별로 저장되며, 같은 워크플로우나 핸드오프 체인의 다운스트림 에이전트가 이를 상속합니다. 템플릿 이름과 상태를 함께 결과로 기록하면 해당 템플릿의 롤링 신뢰 점수도 업데이트됩니다.
| 도구 | 기능 |
|---|---|
record_agent_outcome(session_id, title, kind?, content?, agent_id?, agent_kref?, template_name?, status?, tags?, related_files?, related_krefs?) | 에이전트 결과를 기록합니다. kind: discovery (기본값), decision, lesson, insight, warning, fact, outcome. 신뢰 점수도 업데이트하려면 template_name + status를 전달하세요. |
recall_session_outcomes(session_id, sibling_sessions?, query?, kinds?, limit?) | 같은(또는 관련된) 세션에서 형제 에이전트가 기록한 결과물을 상속합니다. limit 기본값 10. |
record_skill_outcome(skill_name?/skill_kref?, success, summary?, error?, agent_id?, session_id?, duration_ms?) | 단일 스킬 사용의 성공 여부를 기록합니다. |
get_skill_effectiveness(skill_name?/skill_kref?, limit?) | 스킬의 롤링 성공률: {total, successes, failures, rate, recent[]}. limit 기본값 50. |
컨텍스트 압축
섹션 제목: “컨텍스트 압축”대화가 너무 길어지면 operator가 이를 구조화된 요약으로 압축할 수 있습니다. 이 과정은 의도적으로 두 단계로 구성됩니다: 먼저 9개 섹션의 프롬프트 템플릿을 요청하고, 이를 대화에 적용하여 요약을 생성한 다음, 결과를 저장합니다. 압축된 요약은 Kumiho의 CognitiveMemory/compactions/<session_id> 하위에 저장됩니다.
-
템플릿 가져오기.
compact_conversation(session_id?, reason?)을 호출합니다. 9개 섹션의 프롬프트 템플릿이 반환됩니다.reason은 정보 제공용이며 (예:auto-threshold,manual,session-end) 기본값은manual입니다. -
적용하기. 반환된 템플릿을 대화에 적용하여
<analysis>및<summary>태그를 포함한 압축 출력을 생성합니다. -
결과 저장하기. 완전히 적용된 출력을
store_compaction(raw_output, session_id?, source_krefs?)에 전달하여 호출합니다.source_krefs를 전달하면 압축본을 파생된 메모리들과 연결합니다.
권한 관리
섹션 제목: “권한 관리”세션 관리자에서 실행 중인 에이전트는 잠재적으로 위험한 작업을 수행하기 전에 승인을 요청하기 위해 일시 중지할 수 있습니다. operator는 보류 중인 요청을 노출하여 승인 또는 거부할 수 있도록 합니다.
| 도구 | 기능 |
|---|---|
list_pending_permissions() | 관리 중인 모든 에이전트에 걸쳐 보류 중인 권한 요청을 나열합니다. |
respond_to_permission(request_id, action) | 요청을 처리합니다. action: approve 또는 deny. |
권한 요청은 세션 관리자에서 에이전트별로 추적됩니다. 이것은 더 넓은 자율성 수준 & 승인 모델과 연동되는 런타임 승인 인터페이스입니다.
정책 및 자율성 제어
섹션 제목: “정책 및 자율성 제어”낯선 디렉터리에서 에이전트를 생성하거나 셸 명령을 실행하기 전에 사전 정책 검사를 실행할 수 있습니다. 정책은 ~/.revka/config.toml에서 로드되며, 구성된 자율성 규칙에 따라 작업 디렉터리, 명령어, 또는 도구를 검증합니다.
| 도구 | 기능 |
|---|---|
check_policy(cwd?, command?, tool?) | 사전 검사를 실행합니다. 결정을 내린 정책 규칙과 함께 통과/실패 구조체를 반환합니다. cwd는 허용된 루트/금지된 경로에 대해, command는 허용된 명령어/고위험 패턴에 대해, tool은 자동 승인/항상 확인 목록에 대해 검사됩니다. |
get_policy_summary() | 현재 자율성 요약: 정책 수준, 허용된 루트, 명령어 수, 위험 설정. |
자율성 level은 supervised (기본값), autonomous, 또는 locked 중 하나입니다. config.toml에서 읽는 정책 키는 다음과 같습니다:
| 키 | 타입 | 기본값 | 의미 |
|---|---|---|---|
level | string | supervised | 자율성 수준: supervised, autonomous, 또는 locked. |
workspace_dir | string | ~/.revka/workspace | 기본 워크스페이스 루트. |
workspace_only | bool | true | allowed_roots에 포함되지 않은 경로로의 에이전트 접근을 워크스페이스로 제한합니다. |
allowed_roots | string[] | [] | 에이전트가 작업할 수 있는 추가 루트 경로. |
forbidden_paths | string[] | [] | 항상 차단되는 경로. |
allowed_commands | string[] | [] | 셸 실행이 허용된 명령어. |
auto_approve | string[] | [] | 프롬프트 없이 자동 승인되는 도구. |
always_ask | string[] | [] | 항상 승인이 필요한 도구. |
require_approval_for_medium_risk | bool | true | 중간 위험 명령어에 대해 승인을 요구합니다. |
block_high_risk_commands | bool | true | 고위험 명령어 패턴을 완전히 차단합니다. |
max_actions_per_hour | int | 20 | 에이전트 작업에 대한 시간당 속도 제한. |
max_cost_per_day_cents | int | 500 | 일일 LLM 지출 한도 (센트 단위). |