에이전트, 팀, 캔버스

이 페이지에서는 누가 작업을 수행하고 어떻게 진행 상황을 확인하는지를 정의하는 세 가지 오케스트레이션 경로를 다룹니다. Agents 페이지(에이전트 페르소나 레지스트리), Teams 페이지(에이전트를 그룹화하는 위임 토폴로지), Canvas 페이지(에이전트가 구동하는 실시간 비주얼 워크스페이스)가 그것입니다. 세 페이지 모두 대시보드 사이드바의 Orchestration 섹션에 있으며, 동일한 베어러 인증 REST 및 WebSocket API를 통해 게이트웨이와 통신합니다.

UI에서 에이전트와 팀을 직접 생성하려는 경우 이 페이지를 참고하세요. 화면 뒤에 있는 원시 REST 인터페이스는 에이전트, 스킬 & 팀 API를 참고하고, 개념 모델은 에이전트, 팀 & 스웜을 참고하세요.

Agents 페이지

/agents로 이동하면 에이전트 레지스트리를 관리할 수 있습니다. 페이지는 3단 레이아웃으로 구성됩니다. 왼쪽에는 검색 가능한 목록, 가운데에는 선택한 에이전트의 프로필, 오른쪽에는 인스펙터가 있습니다. 툴바에는 Create와 Refresh 버튼이 있습니다.

정체성 / 소울 모델

에이전트는 단순한 모델 이름이 아닌 페르소나입니다. 에이전트 정의는 다음 필드를 포함합니다.

필드	필수 여부	설명
name	필수	사람이 읽을 수 있는 레이블. 에이전트의 item_name으로 슬러그화됩니다(워크플로 YAML의 assign:에서 사용).
identity	필수	에이전트의 정체 — 예: “실용적인 시니어 Rust 엔지니어.” 프롬프트 탭에서 identity seed로도 표시됩니다.
soul	필수	핵심 성격과 철학 — 에이전트의 성향과 가치관.
expertise	선택	집중 분야. 쉼표로 구분하여 입력하면 칩으로 렌더링됩니다(예: rust, async, performance).
tone	선택	커뮤니케이션 스타일 — 예: “간결하고 직접적.”
role	선택	coder, reviewer, researcher 중 하나. 목록의 역할 필터에 사용됩니다.
agent_type	선택	실행 백엔드(아래 참조).
model	선택	모델 오버라이드 옵션. 비어 있으면 설정된 기본값을 사용합니다.
system_hint	선택	런타임에 추가되는 프롬프트 컨텍스트.

name, identity, soul은 유일한 필수 필드이며, 세 필드가 모두 채워져야 Save 버튼이 활성화됩니다.

에이전트 타입

agent_type 드롭다운은 에이전트가 실행될 코딩 백엔드를 선택합니다. 대시보드에서는 다섯 가지를 제공합니다.

값	UI 표시 레이블
claude	Claude
codex	Codex
agy	Antigravity (agy)
agent	Cursor (agent)
opencode	OpenCode (opencode)

프로필의 통계 스트립에는 전체 레지스트리 크기, 활성(비deprecated) 수, codex 타입 에이전트 수가 표시됩니다.

탐색 및 필터링

목록 패널에서는 실시간 필터링을 지원합니다.

• Search는 이름, identity, soul, expertise를 실시간으로 검색합니다.
• 역할 필터는 coder, reviewer, researcher 중 하나(또는 전체)로 범위를 좁힙니다.
• Filter 토글은 deprecated 에이전트를 표시하거나 숨깁니다. 표시 시 deprecated 에이전트는 불투명도가 낮아집니다.

에이전트를 클릭하면 프로필이 열립니다. 프로필 상단에는 아바타, 이름, role / agent_type / model 정보, active / disabled 상태 뱃지가 표시됩니다. 그 아래에는 identity, soul, expertise 섹션과 tone, 리비전 번호, 생성일이 포함된 음성 카드가 있습니다.

오른쪽 인스펙터에는 두 개의 탭이 있습니다.

• Summary — 구조화된 필드(이름, 역할, 타입, 모델, tone, 리비전, 생성일).
• Prompt — 원시 system_hint와 identity seed로 사용되는 identity 텍스트가 모노스페이스로 렌더링됩니다.

에이전트 생성 또는 편집

1. Create(또는 선택한 에이전트의 Edit)를 클릭하여 편집기 모달을 엽니다.

2. name, identity, soul(필수)을 입력하고, 선택적으로 tone, role, type, model, expertise, system hint를 입력합니다.

3. 선택적으로 프로필 이미지를 업로드합니다. PNG, JPEG, WebP만 지원됩니다.

4. Save를 클릭합니다. 대시보드에서 생성/업데이트 요청을 전송한 후, 새 아바타를 선택한 경우 별도 호출로 업로드합니다.

참고

아바타 업로드는 에이전트 생성 또는 업데이트 이후 실행되는 두 번째 API 호출(POST /api/agents/avatar)입니다. 반환된 avatar_url은 HMAC 서명된 시간 제한 워크스페이스 URL이므로 파일시스템을 노출하지 않고 이미지가 렌더링됩니다. 크기 및 형식 제한은 API 레퍼런스를 참고하세요.

선택한 에이전트 프로필에서 Edit, Deprecate / Re-enable(기본 목록에서 숨기는 소프트 토글), Delete(영구 삭제 — 에이전트를 비활성화하려면 삭제보다 deprecation을 권장)를 수행할 수 있습니다.

페이지 뒤의 REST 엔드포인트

메서드	경로	목적
GET	/api/agents?include_deprecated=true&page=1&per_page=200	전체 레지스트리 목록 조회.
POST	/api/agents	에이전트 생성(AgentCreateRequest).
PUT	/api/agents/<kref>	에이전트 업데이트.
POST	/api/agents/avatar	아바타 업로드(multipart: kref, file).
POST	/api/agents/deprecate	deprecated 플래그 토글.
DELETE	/api/agents/<kref>	에이전트 영구 삭제.

모든 라우트에는 Authorization: Bearer <token>이 필요합니다. 전체 요청/응답 형식은 에이전트, 스킬 & 팀 API에서 확인하세요.

Teams 페이지

/teams로 이동하면 에이전트를 위임 토폴로지로 그룹화할 수 있습니다. 팀은 에이전트 멤버 집합과 멤버 간의 관계를 나타내는 방향성 엣지로 구성됩니다. 레이아웃은 Agents 페이지와 동일합니다. 왼쪽에 팀 목록, 가운데에 선택한 팀의 토폴로지, 오른쪽에 멤버/요약 인스펙터가 있습니다.

?team=<kref_or_name>으로 특정 팀에 딥링크할 수 있고, ?member=<kref>로 특정 멤버에 딥링크할 수 있습니다. 클릭 시 두 파라미터가 URL에 기록되므로 팀과 멤버 조합 뷰를 공유할 수 있습니다.

멤버 + 엣지 모델

• 멤버는 에이전트 레지스트리에서 가져온 에이전트 kref입니다.
• 엣지는 두 멤버 간의 방향성 관계입니다. 엣지 타입은 세 가지입니다.

엣지 타입	의미
REPORTS_TO	소스 멤버가 대상 멤버에게 보고합니다(위임 계층).
SUPPORTS	소스 멤버가 대상 멤버를 지원합니다(협업).
DEPENDS_ON	소스 멤버가 대상 멤버의 출력에 의존합니다.

팀 통계 스트립에는 멤버 수, 엣지 수, 상태(active / deprecated)가 표시됩니다.

TeamTopologyPanel

가운데 패널은 TeamTopologyPanel을 렌더링합니다. 이는 @xyflow/react로 구축된 자동 레이아웃 그래프로, 각 노드는 팀 멤버이고 각 엣지는 타입이 지정된 관계입니다. 엣지는 방향 화살표와 타입별 스타일링(색상 및 대시 패턴)으로 그려지며 엣지 타입이 레이블로 표시됩니다. 멤버 노드를 클릭하면 해당 멤버가 선택되고 인스펙터가 Member 탭으로 전환되어 멤버의 kref, 역할, 스킬이 표시되며 에이전트 레지스트리로의 링크가 제공됩니다.

인스펙터의 다른 탭인 Summary에는 전체 팀 메타데이터가 표시됩니다.

위임 엣지로 팀 구성하기

1. Create를 클릭하여 팀 편집기를 엽니다(또는 선택한 팀을 Edit합니다).

2. 팀 name과 선택적 description을 설정하고, 팀 아바타(PNG, JPEG, WebP)를 선택적으로 업로드합니다.

3. Members에서 포함할 에이전트를 체크합니다. 각 카드에는 에이전트의 아바타, 역할, 타입, identity가 표시됩니다.

4. Edge authoring에서 from 멤버, to 멤버, 엣지 타입을 선택하고 Add edge를 클릭합니다. 멤버와 엣지를 추가할 때마다 실시간 토폴로지 미리보기가 업데이트되고, 초안 요약에서 멤버 및 엣지 수를 확인할 수 있습니다.

5. Save를 클릭합니다. 팀에 이름과 멤버가 최소 하나 있어야 버튼이 활성화됩니다.

팁

이미 추가한 두 멤버 사이에만 엣지를 그릴 수 있으며, 멤버 목록에서 제거된 멤버와 연결된 엣지는 편집기에서 자동으로 삭제됩니다. 게이트웨이도 저장 시 그래프를 검증하여 셀프 엣지, 끊어진 참조, 상호 DEPENDS_ON 쌍, 의존성 순환을 거부합니다. 전체 규칙 집합은 엣지 검증을 참고하세요.

선택한 팀에서 Edit, Deprecate / Re-enable, Delete를 수행할 수 있습니다. 에이전트와 마찬가지로 deprecation은 되돌릴 수 있는 소프트 토글이고 삭제는 영구적입니다.

페이지 뒤의 REST 엔드포인트

메서드	경로	목적
GET	/api/teams?include_deprecated=true&page=1&per_page=50	팀 목록 조회(요약 필드만).
GET	/api/teams/<kref>	멤버와 엣지가 해석된 단일 팀 조회.
POST	/api/teams	팀 생성.
PUT	/api/teams/<kref>	팀 업데이트(멤버와 엣지 재조정).
POST	/api/teams/avatar	팀 아바타 업로드(multipart).
POST	/api/teams/deprecate	deprecated 플래그 토글.
DELETE	/api/teams/<kref>	팀 삭제.

목록 엔드포인트는 요약 수만 반환하며, 대시보드는 토폴로지 그래프와 멤버 인스펙터를 채우기 위해 단일 팀을 별도로 조회합니다.

Canvas 페이지

/canvas로 이동하면 실시간 스트리밍 비주얼 워크스페이스를 확인할 수 있습니다. 에이전트는 HTML, SVG, Markdown, 텍스트 형식의 렌더링된 프레임을 명명된 캔버스에 푸시하고, 해당 캔버스를 구독하는 모든 연결된 브라우저 탭에서 각 프레임을 즉시 볼 수 있습니다. 이것이 Revka의 A2UI(에이전트-to-UI) 인터페이스이며, 대시보드는 그 구독자 중 하나입니다.

페이지는 세 개의 컬럼으로 구성됩니다. 왼쪽에 제어 컬럼, 가운데에 라이브 뷰포트, 오른쪽에 프레임 히스토리 스트립이 있습니다.

캔버스 구독

대시보드는 캔버스당 하나의 WebSocket을 엽니다. default라는 이름의 기본 캔버스가 로드 시 미리 선택됩니다.

ws[s]://<host><base>/ws/canvas/<canvas_id>?token=<jwt>

브라우저는 WebSocket에서 Authorization 헤더를 설정할 수 없으므로, revka.v1 채널 서브프로토콜과 함께 bearer.<token> 서브프로토콜로 토큰을 전달합니다.

const ws = new WebSocket(
  "wss://host/ws/canvas/default?token=" + token,
  ["revka.v1", "bearer." + token],
);

다른 캔버스를 보려면 제어 입력란에 캔버스 ID를 입력하고 Switch를 클릭하거나 Enter를 누르세요. 제어 컬럼에는 활성 캔버스 목록도 표시됩니다(GET /api/canvas로 조회하며 5초마다 갱신). 클릭하여 구독할 수 있습니다. 연결 상태 뱃지에 connected / disconnected가 표시되며, Reconnect를 클릭하면 소켓을 다시 엽니다.

실시간 캔버스 프레임

서버에서 푸시하는 각 프레임은 JSON 메시지로 도착합니다.

{
  "type": "frame",
  "canvas_id": "default",
  "frame": {
    "frame_id": "f1a2b3c4-...",
    "content_type": "html",
    "content": "<h1>Build status</h1><p>Green</p>",
    "timestamp": "2026-06-18T12:00:00Z"
  }
}

뷰포트는 현재 프레임을 샌드박스 iframe(sandbox="allow-scripts") 안에 렌더링합니다. 콘텐츠를 감싸는 방식은 content_type에 따라 다릅니다.

content_type	렌더링 방식
html	원시 HTML로 iframe에 직접 표시.
svg	테마 배경의 iframe 뷰포트에 가운데 정렬하여 표시.
markdown	이스케이프 처리 후 서식 있는 텍스트로 표시.
text	이스케이프 처리 후 모노스페이스 서식 텍스트로 표시.
clear	현재 프레임과 히스토리를 지우는 제어 신호.
eval	문서로 렌더링되지 않음.

가운데 패널에는 활성 캔버스 ID, 연결 상태, 현재 프레임 타입, 마지막 업데이트 시간, 현재 프레임 ID가 표시됩니다.

참고

대시보드는 클라이언트 메모리에 최근 50개의 프레임을 유지합니다. 캔버스 상태는 데몬 재시작 시 유지되지 않으며 게이트웨이의 인메모리 캔버스 레지스트리에 저장됩니다. 서버 측 프레임 프로토콜, content-type 허용 목록, 크기 제한은 실시간: WebSocket, SSE & 라이브 캔버스를 참고하세요.

프레임 히스토리와 지우기

오른쪽 히스토리 스트립에는 최근 프레임이 최신순으로 나열되며, 각 항목에는 콘텐츠 타입, 타임스탬프, 짧은 프레임 ID, 콘텐츠 미리보기가 표시됩니다. 항목을 클릭하면 해당 프레임을 뷰포트에 다시 표시합니다. Show / Hide로 스트립을 토글할 수 있습니다.

Clear는 DELETE /api/canvas/<canvas_id>를 전송하여 서버 측 캔버스를 지웁니다. 뷰포트와 로컬 히스토리도 초기화됩니다. 서버에서 clear 프레임이 오는 경우에도 동일한 효과가 발생합니다.

에이전트가 캔버스에 푸시하는 방법

에이전트는 캔버스 REST API를 직접 호출하지 않고 오퍼레이터 도구를 사용합니다.

• **render_canvas**는 명명된 캔버스에 새 프레임을 푸시합니다.
• **clear_canvas**는 캔버스를 지웁니다.

채팅 메시지에 page_context: "canvas"가 포함되면 에이전트는 산문으로 설명하는 대신 render_canvas로 출력을 그리도록 지시받습니다. 에이전트 측 도구와 POST /api/canvas/:id 푸시 엔드포인트는 실시간: WebSocket, SSE & 라이브 캔버스를 참고하세요.

페이지 뒤의 REST 엔드포인트

메서드	경로	목적
GET	/api/canvas	활성 캔버스 ID 목록 조회 → { "canvases": ["default", ...] }.
DELETE	/api/canvas/<canvas_id>	캔버스 지우기 / 삭제.

관련 페이지

에이전트, 스킬 & 팀 API 전체 REST 인터페이스 — 요청/응답 형식, kref 시맨틱, 아바타 제한, 엣지 검증.

실시간: WebSocket, SSE & 라이브 캔버스 서버 측 캔버스 프레임 프로토콜, content-type 허용 목록, render_canvas 도구.

에이전트, 팀 & 스웜 에이전트 페르소나, 팀, 위임의 개념 모델.

워크플로, 편집기 & 실행 워크플로 스텝에서 에이전트(assign:)와 팀(team:)을 참조합니다.

에이전트 스포닝 & 조정 레지스트리와 팀이 정의된 후 런타임에 여러 에이전트를 오케스트레이션합니다.

대시보드 실행 게이트웨이를 시작하고, 디바이스를 페어링하며, 내비게이션을 파악합니다.