에이전트, 팀, 스웜

Revka는 처음부터 멀티 에이전트 방식으로 설계되었습니다. 기본 에이전트는 특화된 서브에이전트에게 작업을 위임하거나, 여러 서브에이전트를 조율된 스웜으로 실행하거나, 의존성 그래프를 통해 서로 보고하는 전체 에이전트 팀을 생성할 수 있습니다. 이 페이지에서는 에이전트 ID 모델과 세 가지 오케스트레이션 레이어를 설명하므로, 작업에 적합한 방식을 선택할 수 있습니다.

두 가지 독립적인 영역이 있으며, 이를 구분해 두면 도움이 됩니다.

• Config 레벨 오케스트레이션 — [agents.<name>] 서브에이전트와 [swarms.<name>] 스웜으로, 내장된 delegate 및 swarm 도구를 통해 구동됩니다. 경량으로 config.toml에 정의되며 모든 에이전트에서 사용할 수 있습니다.
• 운영자 레벨 오케스트레이션 — Agent Template Pool과 Agent Teams로, Operator MCP에 의해 관리되며 Kumiho 그래프 메모리에 저장됩니다. 영속적이고 그래프 기반이며, 신뢰 점수 및 웨이브 실행을 지원합니다.

단일 채팅 내에서 빠르고 선언적인 팬아웃이 필요할 때는 config 레벨 오케스트레이션을 사용하세요. 명시적인 토폴로지를 갖춘 지속적이고 재사용 가능한 에이전트 구성이 필요할 때는 팀을 사용하세요. 에이전트를 연결하는 패턴(리뷰-수정 루프, 핸드오프, 그룹 채팅, 수퍼바이저 위임, 맵-리듀스)은 에이전트 생성 및 조율을 참조하세요.

에이전트 ID 모델

모든 Revka 에이전트는 몇 가지 일급 필드로 구성된 ID를 가집니다. 기본 에이전트는 SOUL.md와 [identity] config 섹션에서 ID를 가져옵니다. 서브에이전트와 풀링된 에이전트도 동일한 구조를 공유하므로, 어디서 실행되든 일관된 동작을 보장합니다.

필드	의미
identity	에이전트의 정체성 — 이름, 역할, 권한 범위.
soul	응답 방식을 형성하는 페르소나, 가치관, 목소리.
expertise	에이전트가 전문으로 하는 도메인 (예: ["Rust", "async"]).
tone	커뮤니케이션 스타일 (예: direct, friendly).
role	기능적 역할: coder, reviewer, researcher, tester, architect, 또는 planner.
model	에이전트 인스턴스화에 사용할 선호 프로바이더/모델.
system_hint	선택적 추가 시스템 프롬프트 안내.

[identity] config 섹션은 기본 에이전트의 시스템 프롬프트에 주입되는 ID 문서의 형식을 제어합니다.

[identity]
format = "aieos"             # "openclaw" or "aieos"
aieos_path = "identity.json" # workspace-relative
# or: aieos_inline = '{"name": "Revka", ...}'

풀링 및 대시보드 관리 에이전트는 동일한 identity/soul/expertise/tone 필드를 Kumiho에 저장합니다. 이러한 필드가 어떻게 유지되고 재사용되는지는 아래의 Agent Template Pool 및 Agent Teams 섹션을 참조하세요.

델리게이트 서브에이전트 — [agents.<name>]

델리게이트 서브에이전트는 config.toml에 정의된 이름 있는 에이전트로, 기본 에이전트가 delegate 도구를 사용하여 하위 작업을 위임할 수 있습니다. 각 서브에이전트는 자체 프로바이더, 모델, 시스템 프롬프트를 가지며, 에이전틱 모드에서는 자체 도구 허용 목록도 갖습니다.

[agents.researcher]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-6"
system_prompt = "You are a research assistant."
max_depth = 2
agentic = true
allowed_tools = ["web_search", "http_request", "file_read"]
max_iterations = 8
agentic_timeout_secs = 600

[agents.coder]
provider = "ollama"
model = "qwen2.5-coder:32b"
temperature = 0.2
timeout_secs = 60

[agents.code_reviewer]
provider = "anthropic"
model = "claude-opus-4-5"
system_prompt = "You are an expert code reviewer focused on security and performance."
agentic = true
allowed_tools = ["file_read", "shell"]
skills_directory = "skills/code-review"

서브에이전트 config 키

키	타입	기본값	의미
provider	string	필수	프로바이더 이름 (anthropic, openrouter, ollama, …).
model	string	필수	서브에이전트에 사용할 모델.
system_prompt	string	미설정	시스템 프롬프트 재정의.
api_key	string	미설정	API 키 재정의 (secrets.encrypt = true일 때 암호화됨).
temperature	float	미설정	온도 재정의.
max_depth	int	3	중첩 위임의 최대 재귀 깊이.
agentic	bool	false	멀티턴 도구 호출 루프 활성화.
allowed_tools	array	[]	에이전틱 모드의 도구 허용 목록.
max_iterations	int	10	에이전틱 모드에서 최대 도구 호출 반복 횟수.
timeout_secs	int	120	비에이전틱 호출의 타임아웃 (1–3600).
agentic_timeout_secs	int	300	에이전틱 루프의 타임아웃 (1–3600).
skills_directory	string	미설정	범위 지정 스킬 로딩을 위한 워크스페이스 상대 스킬 디렉터리.

주의

agentic = true는 allowed_tools에 최소 하나 이상의 항목이 필요합니다. 재진입 위임 루프를 방지하기 위해 delegate 도구는 모든 서브에이전트 허용 목록에서 제외됩니다.

전역 델리게이트 기본값은 별도의 섹션에 정의되며, 자체 타임아웃을 설정하지 않은 모든 서브에이전트에 적용됩니다.

[delegate]
timeout_secs = 120          # non-agentic calls
agentic_timeout_secs = 300  # agentic loops

에이전틱 모드에서 서브에이전트는 풍부한 시스템 프롬프트를 받습니다 — 허용된 도구와 해당 파라미터, 스킬 섹션(skills_directory 또는 기본 워크스페이스 skills/ 디렉터리에서), 워크스페이스 경로, 현재 날짜/시간, 안전 제약 조건, 그리고 shell이 도구 목록에 있을 때의 셸 정책이 포함됩니다.

delegate 도구 사용법

delegate 도구는 하나의 서브에이전트를 실행합니다. 기본적으로 단일 프롬프트 → 응답 방식으로 동작하며, 백그라운드에서는 나중에 확인할 task_id를 반환하고, parallel을 사용하면 여러 이름 있는 에이전트에 동시에 팬아웃합니다.

{ "agent": "researcher",
  "prompt": "Summarize the top 5 recent papers on diffusion models",
  "background": false }

필드	의미
action	delegate (기본값), check_result, list_results, cancel_task.
agent	[agents.<name>]의 서브에이전트 이름.
prompt	하위 작업 프롬프트.
context	프롬프트 앞에 추가되는 선택적 컨텍스트.
background	즉시 task_id를 반환하며 백그라운드 실행.
parallel	동시에 실행할 에이전트 이름 배열.
task_id	check_result / cancel_task와 함께 사용.

백그라운드 워크플로우는 다음과 같습니다: background: true로 delegate 호출 → task_id 수신 → 나중에 action: "check_result"로 delegate 호출. 서브에이전트 프로바이더는 revka doctor로 검증되므로, 프로바이더 이름의 오타가 런타임 이전에 발견됩니다.

스웜 — [swarms.<name>]

스웜은 하나의 전략 아래 여러 이름 있는 서브에이전트를 함께 실행합니다. delegate가 단일 에이전트를 구동하는 반면, swarm 도구는 여러 에이전트를 동시에 조율합니다.

[swarms.analysis]
agents = ["researcher", "coder"]
strategy = "sequential"
description = "Research a topic, then implement the findings."
timeout_secs = 300

키	타입	기본값	의미
agents	array	필수	에이전트 이름; [agents]의 키를 참조해야 합니다.
strategy	string	필수	sequential, parallel, 또는 router.
router_prompt	string	미설정	라우터가 최적의 에이전트를 선택할 때 사용하는 프롬프트.
description	string	미설정	스웜을 선택할 때 LLM에 표시됩니다.
timeout_secs	int	300	최대 스웜 총 실행 시간.

세 가지 전략:

• sequential — 파이프라인 방식. 각 에이전트의 출력이 agents에 나열된 순서대로 다음 에이전트로 전달됩니다.
• parallel — 팬아웃/팬인 방식. 모든 에이전트가 동일한 프롬프트를 받아 실행되며 모든 출력이 수집됩니다.
• router — LLM이 router_prompt를 읽고 작업에 가장 적합한 단일 에이전트를 선택합니다.

swarm 도구로 스웜을 호출합니다.

{ "swarm": "analysis",
  "prompt": "Analyze the competitive landscape for AI code assistants" }

필드	의미
swarm	[swarms.<name>]의 스웜 이름.
prompt	작업 프롬프트.
context	선택적 추가 컨텍스트.

참고

delegate는 단일 에이전트, swarm은 다중 에이전트입니다. 작업이 파이프라인, 팬아웃, 또는 기존에 정의된 서브에이전트 간 라우팅 결정으로 자연스럽게 나뉠 때 스웜을 활용하세요.

Agent Template Pool

config 레벨 서브에이전트를 넘어, Operator MCP는 Kumiho(하네스 프로젝트의 AgentPool 공간 아래)에 영속적인 Agent Template Pool을 유지합니다. 템플릿은 재사용 가능한 에이전트 정의로, 타입, 역할, 기능, ID, 소울, 톤, 선호 모델, 기본 작업 디렉터리를 포함하며 운영자가 필요에 따라 인스턴스화합니다.

템플릿은 전체 ID 모델을 포함합니다.

• role: coder, reviewer, researcher, tester, architect, planner
• agent_type: claude, codex, agy, agent, opencode

운영자는 MCP 도구를 통해 풀 관리 기능을 제공합니다.

도구	목적
save_agent_template	템플릿 생성 또는 업데이트 (이름, 타입, 역할, 기능, ID, 소울, 톤, 모델, …).
search_agent_pool	풀 키워드 검색, 예: {"query": "rust testing agent"}.
list_agent_templates	사용 횟수 기준으로 정렬된 템플릿 목록 조회.
get_agent_trust	템플릿별 성공률 및 최근 실행 결과.

템플릿은 에이전트 생성 시 이름으로 참조됩니다. 운영자의 create_agent 도구는 템플릿을 상속하고 호출 시 필드를 재정의할 수 있습니다.

{ "title": "rust-coder",
  "cwd": "/home/user/myproject",
  "agent_type": "codex",
  "template": "rust-coder",
  "initial_prompt": "Implement the auth module" }

사용 횟수는 자동으로 추적되며, get_agent_trust는 신뢰 인식 패턴에 활용됩니다 — 예를 들어, 리파인먼트 루프는 템플릿의 신뢰 점수가 0.7 이하로 떨어지면 비평가를 자동으로 전환합니다. 대시보드의 에이전트, 팀 & 캔버스 페이지나 Agents API에서도 풀링된 에이전트를 관리할 수 있습니다.

Agent Teams

Agent Team은 에이전트 템플릿을 방향 관계 에지로 연결한 번들로, Kumiho의 Revka/Teams 아래 저장됩니다. 에지는 운영자가 웨이브 방식으로 실행하는 토폴로지(DAG)를 정의합니다. 미해결 의존성이 없는 모든 에이전트가 병렬로 실행된 후 다음 웨이브가 실행되는 방식입니다.

에지 타입은 멤버 간의 관계를 나타냅니다.

• REPORTS_TO
• SUPPORTS
• DEPENDS_ON

팀은 운영자 MCP 도구로 관리됩니다.

도구	목적
create_team	멤버 kref와 에지로 팀 번들 생성/업데이트.
get_team	멤버와 에지를 포함한 팀 전체 상세 정보.
list_teams / search_teams	기존 팀 탐색.
spawn_team	의존성 웨이브 방식으로 팀 실행.
get_spawn_progress	웨이브별 진행 상황, 완료 현황, 중단 이유.
lint_team	역할 균형, 명명 규칙, 기능 커버리지, 에지 완성도 검사.

spawn_team은 실행 제어 파라미터를 받습니다.

파라미터	기본값	의미
task	필수	팀에 주어지는 작업.
cwd	필수	생성된 에이전트의 작업 디렉터리.
halt_on_failure	true	업스트림 에이전트 실패 시 다운스트림 웨이브 중단.
resume_from	미설정	완료된 웨이브를 재실행하지 않고 중단된 스폰을 재개하기 위한 체크포인트 ID.
dry_run	false	에이전트를 실제로 생성하지 않고 웨이브를 검증하고 미리 봅니다.

스폰이 실행 도중 중단되면 응답에 체크포인트 ID가 포함되며, 이를 resume_from에 전달하여 재개할 수 있습니다. 팀 실행은 정적으로, DAG가 사전에 고정됩니다. 이는 수퍼바이저가 지금까지의 결과에 따라 다음 전문가를 동적으로 선택하는 동적 수퍼바이저 위임과 대조됩니다.

팀은 게이트웨이와 대시보드에서도 일급 객체입니다. 팀은 REPORTS_TO / SUPPORTS / DEPENDS_ON 에지로 연결된 에이전트 멤버의 Kumiho 번들이며, supervisor 멤버를 지정할 수 있고 워크플로우의 team: 필드에서 참조할 수 있습니다. 에이전트, 스킬 & 팀 API로 관리하세요.

GET    /api/teams?include_deprecated=false
POST   /api/teams
GET    /api/teams/{*kref}
PUT    /api/teams/{*kref}
DELETE /api/teams/{*kref}
POST   /api/teams/avatar

모든 /api/teams/* 라우트는 페어링 플로우에서 발급된 Authorization: Bearer <token>이 필요합니다.

어떤 레이어를 사용해야 할까요?

하위 작업 위임

[agents.<name>]에 정의된 단일 전문 에이전트를 delegate 도구로 호출합니다. 채팅 내에서 빠르고 범위가 명확한 위임에 적합합니다.

스웜 실행

swarm 도구를 통해 sequential, parallel, 또는 router 전략으로 여러 config 서브에이전트를 함께 실행합니다. 파이프라인과 팬아웃에 적합합니다.

팀 생성

명시적 의존성 에지를 갖는 영속적이고 그래프 기반의 에이전트 구성으로, 웨이브 방식 실행과 체크포인트 재개를 지원합니다. 지속적이고 재사용 가능한 토폴로지에 적합합니다.

동적 조율

리뷰-수정 루프, 리파인먼트, 핸드오프, 그룹 채팅, 수퍼바이저 위임, 맵-리듀스 — 에이전트 생성 및 조율을 참조하세요.

관련 페이지

에이전트 생성 및 조율 운영자 오케스트레이션 패턴: 리뷰-수정, 리파인먼트, 핸드오프, 그룹 채팅, 수퍼바이저, 맵-리듀스.

코드 에이전트, 위임 & 파이프라인 delegate, swarm, CLI 코드 에이전트 도구에 대한 상세 설명.

Config: 프로바이더, 에이전트 & 라우팅 [agents], [swarms], [delegate] 및 라우팅 config의 전체 레퍼런스.

Operator MCP Agent Template Pool과 Teams를 구동하는 오케스트레이션 사이드카.

에이전트 루프 단일 에이전트가 추론하고, 도구를 호출하며, 응답하는 방식.

자율성 수준 & 승인 에이전트의 행동 범위를 제한하는 정책 및 승인 게이트.