에이전트, 스킬, 팀 API

Kumiho에 저장된 에이전트, 스킬, 팀의 CRUD 작업 — 아바타 및 kref 시맨틱 포함.

이 페이지는 에이전트 목록, 스킬 라이브러리, 팀을 관리하는 게이트웨이 엔드포인트를 설명합니다. 이 세 가지 리소스는 대시보드의 Agents, Skills, Teams 페이지에서 생성하고 편집하는 구성 요소입니다. 세 리소스 모두 Kumiho 그래프 메모리에 저장되므로, API를 통해 생성한 정의는 데몬 재시작 후에도 유지되며 워크플로우 YAML에서 참조할 수 있습니다.

대시보드를 클릭하는 대신 레지스트리를 스크립트로 관리하고 싶을 때 이 엔드포인트를 사용하세요. 에이전트 일괄 임포트, 자체 소스에서 스킬 동기화, 또는 배포 파이프라인에 팀 토폴로지를 연결하는 데 활용할 수 있습니다. 대시보드 기능에 대해서는 에이전트, 팀 & 캔버스와 스킬, 도구 & 통합 페이지를 참고하세요. 에이전트, 팀, 스웜의 개념적 모델은 에이전트, 팀 & 스웜을 참고하세요.

인증

이 페이지의 모든 라우트에는 페어링 베어러 토큰이 필요합니다.

Authorization: Bearer <token>

토큰은 페어링 & 인증에서 설명하는 페어링 흐름을 통해 얻을 수 있습니다. 토큰이 없거나 유효하지 않으면 401을 반환합니다. 요청은 게이트웨이의 기본 64 KiB JSON 본문 제한과 요청 타임아웃을 공유하지만, 아바타 업로드 라우트는 예외이며 아래에 별도로 설명합니다.

저장 방식

에이전트, 스킬, 팀은 config.toml에 저장되지 않습니다. 이들은 Kumiho에 아이템, 리비전, (팀의 경우) 번들로 저장됩니다. [kumiho] 하위에서 설정 가능한 두 개의 Kumiho 프로젝트가 사용됩니다.

리소스	Kumiho 프로젝트 (설정 키)	기본 프로젝트	스페이스
에이전트	`kumiho.harness_project`	`Revka`	`AgentPool`
팀	`kumiho.harness_project`	`Revka`	`Teams`
스킬	`kumiho.memory_project`	`CognitiveMemory`	`Skills`

전체 스페이스 경로는 /{project}/{space} 형태입니다. 예를 들어 /Revka/AgentPool 또는 /CognitiveMemory/Skills와 같습니다. 게이트웨이는 첫 쓰기 시 프로젝트와 스페이스를 지연 생성하므로 미리 프로비저닝할 필요가 없습니다.

각 리소스에 대해:

아이템(또는 팀의 경우 번들)이 안정적인 식별자입니다. 이름은 슬러그 형식입니다.
최신 발행 리비전에는 편집 가능한 메타데이터(정체성, 설명, 멤버 수 등)가 저장됩니다.
아티팩트는 더 큰 페이로드를 저장합니다. 아바타 이미지 바이트 또는 스킬의 전체 마크다운이 이에 해당하며, 디스크의 file:// 위치로 참조됩니다.

각 쓰기 작업은 새 리비전을 생성하고 published 태그를 붙이므로, 이력이 보존되고 기존 데이터가 덮어씌워지지 않습니다. 기반 모델에 대해서는 그래프 모델: 스페이스, 아이템 & 프로버넌스를 참고하세요.

kref 형식

kref (kref://…)는 Kumiho 엔티티를 가리키는 표준 포인터입니다. 아이템은 다음 형태를 사용합니다.

kref://<Project>/<Space>/<slug>.<suffix>

예시:

kref://Revka/AgentPool/senior-rust-engineer.agent
kref://CognitiveMemory/Skills/debugging-skills.skill
kref://Revka/Teams/platform-team

슬러그는 제공된 name에서 파생됩니다. 소문자로 변환하고, 영숫자가 아닌 모든 문자를 하이픈으로 대체하며, 연속된 하이픈을 하나로 압축합니다. 예를 들어 "Senior Rust Engineer"는 senior-rust-engineer가 됩니다. 이 슬러그는 워크플로우 YAML의 assign:(에이전트)과 team:(팀)에서 사용하는 값과 정확히 일치하므로, 응답에서 사람이 읽기 쉬운 name과 구분하여 item_name으로 별도 반환됩니다.

리비전 kref에는 선택자가 추가됩니다. 예: kref://Revka/AgentPool/senior-rust-engineer.agent?r=3&a=SKILL.md. URL 경로에 kref를 전달하면 에이전트 및 팀 라우트는 kref:// 접두사를 자동으로 제거하고 다시 추가하므로, {*kref} 경로 세그먼트에서 kref://Revka/...와 Revka/... 모두 사용할 수 있습니다. 스킬 상세 조회, 수정, 삭제 라우트는 이 정규화를 수행하지 않으므로, 해당 라우트에서는 kref:// 접두사를 생략하고 경로 세그먼트를 직접 전달해야 합니다(예: CognitiveMemory/Skills/debugging-skills.skill).

에이전트 관리

에이전트는 AgentPool 스페이스에서 agent 종류로 저장되는 Kumiho 아이템입니다. 각 에이전트에는 정체성, 소울, 전문성, 어조, 역할, 유형, 선택적 모델 오버라이드, 선택적 시스템 힌트가 포함됩니다.

엔드포인트

GET    /api/agents
POST   /api/agents
PUT    /api/agents/{*kref}
DELETE /api/agents/{*kref}
POST   /api/agents/deprecate
POST   /api/agents/avatar

에이전트 목록 조회

GET /api/agents?include_deprecated=false&q=rust&page=1&per_page=9
Authorization: Bearer <token>

쿼리 파라미터	타입	기본값	의미
`include_deprecated`	bool	`false`	비활성화된 에이전트를 결과에 포함합니다.
`q`	string	—	전문 검색. 값이 있으면 일반 목록 대신 Kumiho 검색을 사용합니다.
`page`	int	`1`	1부터 시작하는 페이지 번호.
`per_page`	int	`9`	페이지당 항목 수. 1~50 범위로 제한됩니다.

응답:

{
  "agents": [
    {
      "kref": "kref://Revka/AgentPool/senior-rust-engineer.agent",
      "name": "Senior Rust Engineer",
      "item_name": "senior-rust-engineer",
      "kind": "agent",
      "deprecated": false,
      "created_at": "2026-06-18T00:00:00Z",
      "identity": "...",
      "soul": "...",
      "expertise": ["Rust", "async"],
      "tone": "direct",
      "role": "engineer",
      "agent_type": "specialist",
      "model": "claude-opus-4",
      "system_hint": "...",
      "revision": 3,
      "revision_number": 3,
      "avatar_url": "/workspace/...?sig=...&expires=...",
      "avatar_artifact_name": "profile-avatar",
      "avatar_filename": "headshot.png",
      "avatar_mime": "image/png"
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 9
}

검색을 사용하지 않는 목록 응답은 빠른 대시보드 폴링을 흡수하기 위해 프로세스 내 3초 캐시로 제공됩니다. 캐시는 모든 쓰기 작업 시 무효화됩니다.

에이전트 생성

POST /api/agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Senior Rust Engineer",
  "identity": "A pragmatic systems engineer.",
  "soul": "Calm, precise, allergic to overengineering.",
  "expertise": ["Rust", "async", "tokio"],
  "tone": "direct",
  "role": "engineer",
  "agent_type": "specialist",
  "model": "claude-opus-4",
  "system_hint": "Prefer the smallest correct change."
}

name, identity, soul은 필수이며 나머지는 선택 사항입니다. 성공 시 { "agent": { ... } } 형태의 201 Created를 반환합니다. name을 슬러그로 변환하여 아이템 식별자로 사용하고, 메타데이터를 담은 리비전을 작성한 후 published 태그를 붙입니다.

에이전트 수정

PUT /api/agents/kref://Revka/AgentPool/senior-rust-engineer.agent
Authorization: Bearer <token>
Content-Type: application/json

요청 본문 형태는 생성과 동일합니다. 수정 시 기존 리비전을 편집하는 것이 아니라 새 리비전을 작성하고 published 태그를 다시 붙입니다. 기존 아바타 메타데이터는 수정 후에도 유지되므로 필드를 편집해도 에이전트의 아바타가 삭제되지 않습니다.

에이전트 비활성화

POST /api/agents/deprecate
Authorization: Bearer <token>
Content-Type: application/json

{ "kref": "kref://Revka/AgentPool/senior-rust-engineer.agent", "deprecated": true }

비활성화는 소프트 토글입니다. 비활성화된 에이전트는 기본 목록에서 숨겨지지만 include_deprecated=true를 전달하면 다시 표시됩니다. "deprecated": false로 설정하면 재활성화됩니다.

에이전트 삭제

DELETE /api/agents/kref://Revka/AgentPool/senior-rust-engineer.agent
Authorization: Bearer <token>

204 No Content를 반환합니다. 이 작업은 아이템을 영구적으로 삭제합니다. 에이전트를 단순히 비활성화하려면 삭제 대신 비활성화를 사용하세요.

스킬 관리

스킬은 Skills 스페이스에서 skill 종류로 저장되는 Kumiho 아이템입니다. 스킬은 마크다운 문서와 경량 메타데이터로 구성됩니다. 목록 응답의 크기를 줄이기 위해 게이트웨이는 저장소를 두 부분으로 분리합니다.

리비전 메타데이터에는 description, domain, tags, created_by만 저장됩니다.
전체 마크다운은 ~/.revka/workspace/skills/<slug>.md에 저장되고, file:// URI를 location으로 하는 SKILL.md 아티팩트로 참조됩니다. 콘텐츠는 상세 보기 및 편집 시 디스크에서 읽어옵니다.

엔드포인트

GET    /api/skills
POST   /api/skills
GET    /api/skills/{*kref}
PUT    /api/skills/{*kref}
DELETE /api/skills/{*kref}
POST   /api/skills/deprecate

스킬 목록 조회

GET /api/skills?include_deprecated=false&q=debug&page=1&per_page=9
Authorization: Bearer <token>

쿼리 파라미터는 에이전트 목록과 동일합니다(include_deprecated, q, page, per_page; per_page는 1~50으로 제한). 목록 응답에서는 전체 콘텐츠를 생략합니다. content 필드는 비어 있거나(콘텐츠를 인라인으로 저장한 레거시 스킬의 경우 200자 미리보기), Kumiho의 gRPC 제한을 초과하지 않도록 유지됩니다. 전체 마크다운을 읽으려면 상세 엔드포인트를 사용하세요. 검색은 현재의 skill 종류와 레거시 skilldef 종류 모두를 처리합니다. 검색을 사용하지 않는 결과는 30초간 캐시됩니다.

{
  "skills": [
    {
      "kref": "kref://CognitiveMemory/Skills/debugging-skills.skill",
      "name": "debugging-skills",
      "item_name": "debugging-skills",
      "deprecated": false,
      "created_at": "2026-06-18T00:00:00Z",
      "description": "Systematic debugging workflow",
      "content": "",
      "domain": "engineering",
      "tags": ["debug"],
      "revision_number": 2
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 9
}

스킬 단건 조회 (콘텐츠 포함)

GET /api/skills/kref://CognitiveMemory/Skills/debugging-skills.skill
Authorization: Bearer <token>

content 필드가 채워진 { "skill": { ... } }를 반환합니다. 콘텐츠는 다음 우선순위로 해석됩니다. 아티팩트 위치를 통한 로컬 파일, 아티팩트 메타데이터, 리비전 메타데이터 순입니다(후자 두 가지는 ClawHub 및 매우 오래된 설치 환경을 지원합니다).

스킬 생성

POST /api/skills
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Debugging skills",
  "description": "Systematic debugging workflow",
  "content": "# Debugging\n\nReproduce, minimise, hypothesise...",
  "domain": "engineering",
  "tags": ["debug"]
}

name, description, content, domain은 필수이며 tags는 선택 사항입니다. 생성 흐름에서는 name을 슬러그로 변환하고, 리비전 메타데이터를 작성하며, 마크다운을 SKILL.md 아티팩트로 디스크에 저장한 후 리비전에 published 태그를 붙입니다. 201 Created를 반환합니다.

스킬 수정

PUT /api/skills/kref://CognitiveMemory/Skills/debugging-skills.skill
Authorization: Bearer <token>
Content-Type: application/json

요청 본문 형태는 생성과 동일합니다. 수정 시 새 리비전을 작성하고, 마크다운 파일을 다시 쓰며, 새 SKILL.md 아티팩트를 첨부한 후 재발행합니다.

비활성화 및 삭제

POST   /api/skills/deprecate      Body: { "kref": "...", "deprecated": true }
DELETE /api/skills/{*kref}        Returns 204 No Content

비활성화는 에이전트와 동일하게 작동합니다. 기본 목록 표시 여부를 제어하는 소프트 토글입니다. 삭제는 영구적입니다.

팀 관리

팀은 Teams 스페이스의 Kumiho 번들입니다. 번들은 에이전트 멤버를 그룹화하며, 멤버 간 방향성 엣지로 위임 토폴로지를 표현합니다. 엣지 유형은 REPORTS_TO, SUPPORTS, DEPENDS_ON입니다. 팀은 워크플로우 YAML의 team: 필드에서 참조할 수 있습니다.

엔드포인트

GET    /api/teams
POST   /api/teams
GET    /api/teams/{*kref}
PUT    /api/teams/{*kref}
DELETE /api/teams/{*kref}
POST   /api/teams/deprecate
POST   /api/teams/avatar

팀 목록 조회

GET /api/teams?include_deprecated=false&page=1&per_page=9
Authorization: Bearer <token>

쿼리 파라미터	타입	기본값	의미
`include_deprecated`	bool	`false`	비활성화된 팀을 포함합니다.
`page`	int	`1`	1부터 시작하는 페이지 번호.
`per_page`	int	`9`	페이지당 항목 수. 1~50으로 제한됩니다.

목록 엔드포인트는 번들 메타데이터에서 요약 필드(member_count, member_names, edge_count)만 반환합니다. 각 팀의 전체 멤버 정보를 가져오지는 않습니다. 멤버 및 엣지 목록을 완전히 해석하려면 단건 조회 엔드포인트를 사용하세요. 결과는 30초간 캐시됩니다.

팀 단건 조회

GET /api/teams/kref://Revka/Teams/platform-team
Authorization: Bearer <token>

멤버와 엣지가 완전히 해석된 팀 전체 정보를 반환합니다.

{
  "team": {
    "kref": "kref://Revka/Teams/platform-team",
    "name": "Platform Team",
    "description": "Owns the runtime and deploy pipeline.",
    "deprecated": false,
    "created_at": "2026-06-18T00:00:00Z",
    "members": [
      {
        "kref": "kref://Revka/AgentPool/senior-rust-engineer.agent",
        "name": "senior-rust-engineer",
        "role": "engineer",
        "agent_type": "specialist",
        "identity": "...",
        "expertise": ["Rust"],
        "avatar_url": "/workspace/...?sig=..."
      }
    ],
    "edges": [
      {
        "from_kref": "kref://Revka/AgentPool/junior.agent",
        "to_kref": "kref://Revka/AgentPool/senior-rust-engineer.agent",
        "edge_type": "REPORTS_TO"
      }
    ],
    "avatar_url": null,
    "avatar_artifact_name": null,
    "avatar_filename": null,
    "avatar_mime": null
  }
}

팀 생성

POST /api/teams
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Platform Team",
  "description": "Owns the runtime and deploy pipeline.",
  "members": [
    "kref://Revka/AgentPool/senior-rust-engineer.agent",
    "kref://Revka/AgentPool/junior.agent"
  ],
  "edges": [
    {
      "from_kref": "kref://Revka/AgentPool/junior.agent",
      "to_kref": "kref://Revka/AgentPool/senior-rust-engineer.agent",
      "edge_type": "REPORTS_TO"
    }
  ]
}

name은 필수이며 description, members(에이전트 kref), edges는 선택 사항입니다. 게이트웨이는 번들을 생성하고, 각 멤버를 추가하며, 엣지를 생성합니다. 성공 시 완전히 구성된 팀과 함께 201 Created를 반환합니다.

엣지 유효성 검사

저장 전에 게이트웨이는 팀 그래프의 유효성을 검사하며, 유효하지 않을 경우 400과 validation_errors 배열을 반환합니다. 검사 항목은 다음과 같습니다.

코드	발생 조건
`self_edge`	`from_kref`와 `to_kref`가 같은 엣지.
`dangling_ref`	엣지의 엔드포인트가 `members` 목록에 없음.
`reciprocal_depends`	동일한 쌍 사이에 두 개의 `DEPENDS_ON` 엣지가 양방향으로 존재함.
`cycle`	실행 엣지(`DEPENDS_ON`, `SUPPORTS`, `FEEDS_INTO`)가 의존성 순환을 형성함.

{
  "error": "Team graph is invalid",
  "validation_errors": [
    { "code": "cycle", "message": "Dependency cycle detected among 2 member(s). ..." }
  ]
}

팀 수정

PUT /api/teams/kref://Revka/Teams/platform-team
Authorization: Bearer <token>
Content-Type: application/json

요청 본문 형태는 생성과 동일합니다. 수정 시 그래프를 재검증하고, 새 메타데이터 리비전을 작성한 후 상태를 조정합니다. 새로 추가된 멤버를 추가하고, 제거된 멤버를 삭제하며, 멤버 간 기존 엣지를 모두 삭제한 후 요청에 있는 엣지를 다시 생성합니다. 기존 아바타 메타데이터는 유지됩니다.

비활성화 및 삭제

POST   /api/teams/deprecate      Body: { "kref": "...", "deprecated": true }
DELETE /api/teams/{*kref}        Returns 204 No Content

deprecate는 { "success": true }를 반환합니다. 삭제 시 먼저 멤버 간 엣지와 번들 멤버십을 제거한 후 번들 자체를 삭제합니다.

아바타 업로드

에이전트와 팀은 아바타 이미지를 지원합니다. 스킬은 지원하지 않습니다.

POST /api/agents/avatar
POST /api/teams/avatar
Authorization: Bearer <token>
Content-Type: multipart/form-data

멀티파트 필드:

필드	필수 여부	의미
`kref`	필수	에이전트 아이템 kref 또는 팀 번들 kref.
`file`	필수	이미지 바이트.

제약 사항:

최대 크기: 파일당 5 MiB. 더 큰 업로드는 413 Payload Too Large를 반환합니다.
허용 형식: 선언된 MIME 타입이 아닌 콘텐츠(매직 바이트)로 감지된 PNG, JPEG, WebP. SVG는 명시적으로 거부됩니다. 지원하지 않는 타입은 415 Unsupported Media Type을 반환합니다.
이 두 라우트는 게이트웨이의 기본 JSON 본문 제한과 별도로 60초 타임아웃을 가진 전용 라우터에서 실행됩니다.

성공 시 엔드포인트는 업데이트된 에이전트 또는 팀 객체를 반환합니다. 이미지 바이트는 워크스페이스 디렉터리(artifacts/<project>/<space>/<slug>/avatars/<uuid>.<ext>) 하위에 저장되고, profile-avatar라는 이름의 Kumiho 아티팩트로 기록되며, 파일 경로는 리비전 메타데이터에 저장됩니다. 반환된 avatar_url은 워크스페이스 에셋 엔드포인트에서 제공하는 HMAC 서명된 시간 제한 URL입니다. 에이전트 아바타 URL은 24시간 동안 유효합니다. 이를 통해 브라우저가 임의의 파일시스템 접근 없이 이미지를 렌더링할 수 있습니다. 서명된 워크스페이스 URL의 작동 방식은 TLS, 속도 제한, WebAuthn & 정적 제공을 참고하세요.

curl을 사용한 예시:

curl -X POST https://<gateway>/api/agents/avatar \
  -H "Authorization: Bearer $TOKEN" \
  -F "kref=kref://Revka/AgentPool/senior-rust-engineer.agent" \
  -F "[email protected]"

오류

이 라우트들은 게이트웨이의 중앙 Kumiho 오류 매핑을 공유합니다. 목록 호출에서 Kumiho가 404를 반환하면 “스페이스가 아직 생성되지 않음”으로 처리합니다. 게이트웨이는 프로젝트와 스페이스를 프로비저닝하고 오류 대신 빈 목록을 반환합니다. 기타 업스트림 실패(5xx 포함)는 일관된 게이트웨이 오류 형식으로 표시됩니다. 일반적으로 kumiho_upstream_unavailable 이유와 함께 503을 반환하므로, 대시보드는 예측 가능한 단일 오류 상태를 렌더링할 수 있습니다.

에이전트, 스킬, 팀 API

인증

저장 방식

kref 형식

에이전트 관리

엔드포인트

에이전트 목록 조회

에이전트 생성

에이전트 수정

에이전트 비활성화

에이전트 삭제

스킬 관리

엔드포인트

스킬 목록 조회

스킬 단건 조회 (콘텐츠 포함)

스킬 생성

스킬 수정

비활성화 및 삭제

팀 관리

엔드포인트

팀 목록 조회

팀 단건 조회

팀 생성

엣지 유효성 검사

팀 수정

비활성화 및 삭제

아바타 업로드

오류

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조