워크플로우 및 Architect API

워크플로우 정의 CRUD, 실행 라이프사이클, 승인, 그리고 AI 지원 Architect 패널.

이 페이지는 워크플로우 정의와 워크플로우 실행을 관리하는 게이트웨이 엔드포인트와, AI 지원 수정안을 제안하는 Architect 패널을 설명합니다. 이 라우트들은 대시보드의 Workflows 페이지에서 호출하며, UI를 직접 클릭하지 않고 워크플로우를 생성·실행·승인·재시도·모니터링하고 싶을 때 스크립트로 활용할 수 있습니다.

워크플로우 정의는 Kumiho 그래프 메모리에 저장되는 선언형 YAML 파이프라인으로, operator-mcp 백엔드가 이를 실행합니다. YAML 작성 방법은 첫 번째 워크플로우와 워크플로우 YAML 레퍼런스를 참고하세요. 이 페이지는 워크플로우를 둘러싼 HTTP 인터페이스를 다룹니다. 대시보드 UI에 대해서는 워크플로우, 편집기 및 실행을 참고하세요.

인증

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

Authorization: Bearer <token>

토큰 발급 방법은 페어링 및 인증을 참고하세요. 토큰이 없거나 유효하지 않으면 401을 반환합니다. 대부분의 라우트는 게이트웨이 기본값인 64 KiB JSON 본문 한도 및 요청 타임아웃을 공유하며, 두 가지 예외가 있습니다. 워크플로우 정의의 POST/PUT은 16 MiB 본문을 허용하고(실제 워크플로우가 64 KiB를 초과할 수 있음), operator 도구 기반 라우트(run, approve, retry, cancel, Architect)는 각각 고정된 operator 타임아웃을 사용합니다.

스토리지 동작 방식

워크플로우 정의와 실행 기록은 config.toml이 아닌 Kumiho에 저장됩니다.

리소스	Kumiho 스페이스	아이템 종류
정의	`Revka/Workflows`	`workflow`
실행 기록	`Revka/WorkflowRuns`	`workflow_run`
실행 요청	`Revka/WorkflowRunRequests`	`workflow-run-request`

각 정의는 Kumiho 아이템으로 저장되며, 최신 발행된 리비전에 메타데이터가 담겨 있고, YAML 본문은 메타데이터 인라인이 아닌 workflow.yaml 리비전 아티팩트로 별도 저장됩니다(Kumiho 크기 제한 준수). 저장할 때마다 새 리비전이 작성되고 published 태그가 붙으므로 히스토리가 보존되며, 각 실행은 실행 당시의 정확한 리비전에 고정됩니다. 게이트웨이는 첫 번째 쓰기 시 프로젝트와 스페이스를 지연 생성합니다.

워크플로우 정의

엔드포인트

GET    /api/workflows
POST   /api/workflows                       (16 MiB body)
PUT    /api/workflows/{*kref}               (16 MiB body)
DELETE /api/workflows/{*kref}
POST   /api/workflows/deprecate
GET    /api/workflows/revisions/{*kref}

{*kref} 세그먼트는 스킴을 제외한 경로만 입력해야 합니다. 예: Revka/Workflows/my-flow.workflow(kref:// 프리픽스 없음). PUT과 DELETE는 스킴을 자체적으로 앞에 붙이므로, 프리픽스를 포함하면 이중으로 붙게 됩니다. 단, GET /api/workflows/revisions/{*kref}는 예외적으로 선두의 kref:// 프리픽스를 제거한 뒤 아이템을 조회합니다.

정의 목록 조회

GET /api/workflows?include_deprecated=false&include_definition=true&q=report
Authorization: Bearer <token>

쿼리 파라미터	타입	기본값	설명
`include_deprecated`	bool	`false`	폐기된 워크플로우를 결과에 포함합니다.
`include_definition`	bool	`true`	각 항목에 전체 YAML을 포함합니다. 가벼운 목록이 필요하면 `false`로 설정하세요.
`q`	string	—	정의 전체에 대한 전문 검색.

검색이 아닌 목록 응답은 대시보드 폴링 부하를 흡수하기 위해 약 30초의 인프로세스 캐시에서 제공되며, 쓰기 작업이 발생할 때마다 캐시가 무효화됩니다.

정의 생성

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

{
  "name": "daily-report",
  "description": "Summarise yesterday and email the team.",
  "definition": "name: daily-report\nversion: \"1.0\"\nsteps:\n  - id: summarize\n    action: summarize\n    agent:\n      prompt: \"Summarise ${inputs.topic}.\"\n",
  "version": "1.0",
  "tags": ["reporting"]
}

필드	필수 여부	설명
`name`	필수	표시 이름. 슬러그로 변환되어 아이템 식별자가 됩니다.
`description`	필수	사람이 읽을 수 있는 용도 설명.
`definition`	필수	문자열 형태의 전체 워크플로우 YAML.
`version`	선택	시맨틱 버전 레이블.
`tags`	선택	검색 및 필터링을 위한 분류 목록.

저장 전에 게이트웨이는 operator의 유효성 검사기를 호출하여 YAML을 검증합니다(유효성 검사 참고). 성공하면 name을 슬러그로 변환하고, 메타데이터 리비전을 기록하며, YAML을 workflow.yaml 아티팩트로 저장하고, 리비전에 published 태그를 붙인 뒤 { "workflow": { ... } }와 함께 201 Created를 반환합니다. 크론 잡도 동기화되고 workflow.revision.published 이벤트가 브로드캐스트됩니다.

정의 수정

PUT /api/workflows/Revka/Workflows/daily-report.workflow
Authorization: Bearer <token>
Content-Type: application/json

요청 본문 형식은 생성과 동일합니다. 수정은 기존 리비전을 직접 편집하지 않고 새 리비전을 작성하며, published 태그를 재지정하고 크론 잡을 재동기화한 뒤 workflow.revision.published를 브로드캐스트합니다. 이전 리비전이 보존되므로 진행 중이거나 완료된 실행은 실제로 실행된 YAML을 계속 표시할 수 있습니다.

정의 폐기

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

{ "kref": "kref://Revka/Workflows/daily-report.workflow", "deprecated": true }

폐기는 소프트 토글입니다. 폐기된 워크플로우는 기본 목록에서 숨겨지며(include_deprecated=true를 전달하면 표시), 크론 잡도 제거됩니다. "deprecated": false로 설정하면 워크플로우를 복원하고 크론 트리거를 재등록합니다.

정의 삭제

DELETE /api/workflows/Revka/Workflows/daily-report.workflow
Authorization: Bearer <token>

204 No Content를 반환합니다. 아이템과 크론 잡을 영구적으로 제거합니다. 워크플로우를 단순히 비활성화하려면 삭제 대신 폐기를 사용하세요.

특정 리비전 조회

GET /api/workflows/revisions/kref://Revka/Workflows/daily-report.workflow?r=3
Authorization: Bearer <token>

현재 published 태그와 관계없이 해당 정확한 리비전 kref에 고정된 YAML과 함께 { "workflow": { ... } }를 반환합니다. 대시보드의 실행 뷰어는 이를 사용하여 실행이 수행된 정확한 정의를 렌더링합니다. workflow.yaml 아티팩트가 없는 리비전은 404를 반환합니다.

워크플로우 실행

**실행(run)**은 정의의 단일 실행 인스턴스입니다. 실행을 트리거하면 Kumiho에 영속적인 workflow-run-request 아이템이 생성되고 빠른 시작을 위해 operator의 run_workflow 도구가 즉시 호출됩니다. 직접 호출이 실패하더라도 요청 아이템은 operator의 리스너에 의해 처리됩니다. 실행 상태는 Kumiho 실행 레코드에 로컬 체크포인트 데이터를 오버레이하여 보고되므로 진행 상황이 최신 상태로 유지됩니다.

엔드포인트

GET    /api/workflows/runs
GET    /api/workflows/runs/{run_id}
POST   /api/workflows/run/{name}
POST   /api/workflows/runs/{run_id}/approve
POST   /api/workflows/runs/{run_id}/retry
POST   /api/workflows/runs/{run_id}/cancel
DELETE /api/workflows/runs/{run_id}

실행 상태

상태	의미
`pending`	생성되었지만 실행기에 아직 할당되지 않은 상태.
`running`	실행기가 활성 상태.
`paused`	인간 승인 또는 인간 입력 게이트에서 대기 중.
`completed`	모든 단계가 성공적으로 완료됨.
`failed`	단계 실패. 체크포인트가 보존되어 재시도 가능.
`cancelled`	사용자 또는 시스템에 의해 중단됨.
`stale`	체크포인트도 라이브 잠금도 없는 비종료 상태(예: 재배포로 로컬 상태가 지워진 경우).

실행 목록 조회

GET /api/workflows/runs?limit=20&workflow=daily-report
Authorization: Bearer <token>

쿼리 파라미터	타입	기본값	설명
`limit`	int	`20`	반환할 최근 실행의 최대 수.
`workflow`	string	—	특정 워크플로우 이름으로 실행을 필터링.

최신 순으로 { "runs": [...], "count": N }을 반환합니다.

단일 실행 조회

GET /api/workflows/runs/{run_id}
Authorization: Bearer <token>

단계별 상세 정보와 함께 { "run": { ... } }를 반환합니다. 라이브 실행은 실행기의 인메모리 상태에서 읽어오고, 완료된 실행은 Kumiho 실행 레코드에서 가져옵니다. 알 수 없는 run_id는 404를 반환합니다.

실행 트리거

POST /api/workflows/run/daily-report
Authorization: Bearer <token>
Content-Type: application/json

{
  "inputs": { "topic": "AI safety" },
  "cwd": "/path/to/project",
  "target_step_id": "summarize"
}

필드	필수 여부	설명
`inputs`	선택	워크플로우 입력 이름과 값을 매핑하는 객체.
`cwd`	선택	셸/에이전트 단계를 위한 작업 디렉터리.
`target_step_id`	선택	”여기까지 실행” — 이 단계의 전이 의존 단계들과 해당 단계만 실행하고 중지.

경로 세그먼트는 kref가 아닌 워크플로우 이름입니다. 디스패치 전에 워크플로우가 검증되며, 잘못된 정의나 알 수 없는 target_step_id는 유효성 검사 오류 본문과 함께 400을 반환합니다. 성공 시 응답은 다음과 같습니다.

{ "run_id": "<uuid>", "workflow": "daily-report", "status": "pending" }

인간 승인 게이트

워크플로우는 YAML에 정의된 human_approval 단계에서 operator가 승인하거나 거부할 때까지 일시 중지할 수 있습니다. 게이트를 해결하려면 다음을 사용하세요.

POST /api/workflows/runs/{run_id}/approve
Authorization: Bearer <token>
Content-Type: application/json

{ "approved": true, "feedback": "LGTM" }

필드	필수 여부	설명
`approved`	필수	워크플로우를 계속하려면 `true`, 거부하려면 `false`.
`feedback`	선택	결정과 함께 기록되는 자유 형식 메모.

게이트웨이는 재개 전에 내부 레지스트리에서 원자적으로 승인을 클레임하므로, 동시에 승인이 도착하더라도(예: 대시보드 클릭과 Discord 응답이 동시에 도착) 게이트가 이중으로 해결되지 않습니다. 이후 operator의 resume_workflow 도구를 호출하고, 결정을 감사 기록에 남기며, human_approval_resolved SSE 이벤트를 브로드캐스트합니다. 성공적인 호출은 다음을 반환합니다.

{ "status": "ok", "message": "Workflow approved", "run_id": "<uuid>", "approved": true }

실패한 실행 재시도

POST /api/workflows/runs/{run_id}/retry
Authorization: Bearer <token>
Content-Type: application/json

{ "cwd": "/path/to/project" }

본문은 선택 사항입니다. 재시도는 첫 번째 실패한 단계부터 다시 실행하며, 성공한 단계의 출력은 체크포인트에서 보존되므로 실패한 단계와 그 다운스트림 단계만 다시 실행됩니다. workflow_retry SSE 이벤트를 브로드캐스트하고 operator 도구의 결과 페이로드를 반환합니다.

실행 중인 실행 취소

POST /api/workflows/runs/{run_id}/cancel
Authorization: Bearer <token>

본문 없음. 취소는 cancel_workflow 도구를 통해 실행기의 취소 플래그를 설정하며, 실행기는 다음 단계 경계에서 이를 읽어 진행 중인 셸 또는 파이썬 서브프로세스를 종료하고 실행 상태를 cancelled로 전환합니다. HTTP 상태는 결과에 따라 달라집니다.

상태	조건
`200 OK`	실행이 활성 상태였으며 취소가 요청됨.
`404 Not Found`	실행이 활성 레지스트리에 없음(이미 완료되었거나 알 수 없는 경우).
`409 Conflict`	실행이 이미 종료 상태.

취소 성공 시 workflow_cancel SSE 이벤트가 브로드캐스트됩니다.

실행 삭제

DELETE /api/workflows/runs/{run_id}
Authorization: Bearer <token>

204 No Content를 반환합니다. Revka/WorkflowRuns에서 실행 레코드를 삭제하고 로컬 파일을 최선을 다해 정리합니다. 체크포인트(~/.revka/workflow_checkpoints/{run_id}.json)와 실행별 아티팩트 디렉터리가 해당됩니다.

대시보드 통계 엔드포인트

단일 집계 호출로 Workflows 랜딩 페이지를 구동하므로, 정의와 실행 요청을 별도로 팬아웃할 필요가 없습니다.

GET /api/workflows/dashboard?include_definition=true
Authorization: Bearer <token>

include_definition(기본값 true)은 각 정의에 YAML을 포함할지 여부를 제어합니다. 응답은 dashboard로 래핑됩니다.

{
  "dashboard": {
    "definitions_count": 12,
    "definitions": [ ... ],
    "active_runs": 2,
    "recent_runs": [ ... ],
    "total_runs": 47
  }
}

active_runs는 running 또는 paused 상태의 실행 수를 나타내며, recent_runs는 가장 최근 실행 목록입니다.

에이전트 활동 로그

대시보드의 라이브 실행 뷰를 위해, 워크플로우 내에서 실행되는 각 에이전트는 에이전트별 JSONL 실행 로그를 유지합니다. 해당 에이전트의 도구 호출, 메시지, 결과를 드릴다운하려면 다음을 사용하세요.

GET /api/workflows/agent-activity/{agent_id}?view=summary&limit=100
Authorization: Bearer <token>

쿼리 파라미터	타입	기본값	설명
`view`	string	`summary`	`summary`, `tool_calls`, `messages`, `errors`, `full` 중 하나.
`limit`	int	`100`	반환할 최대 항목 수(`500`으로 제한).

summary 뷰는 헤더, 전체 이벤트 수, 도구 호출 수, 오류 수, 마지막 메시지(잘림), 최근 도구 호출, 집계된 토큰 사용량 통계를 반환합니다. 다른 뷰는 일치하는 필터링된 항목을 최신 순으로 반환합니다. 로그가 없는 에이전트는 404를 반환합니다. 로그 파일은 ~/.revka/operator_mcp/runlogs/{agent_id}.jsonl에 있습니다.

Architect — AI 지원 워크플로우 수정

워크플로우 편집기의 Architect 패널은 워크플로우에 대한 구조적 편집을 제안하고, 수정안을 미리 보고, 검증하고, 되돌릴 수 있게 합니다. 네 가지 라우트 모두 인증이 필요하며, operator 기반 라우트는 30초의 operator 도구 타임아웃을 사용합니다. Architect는 operator-mcp 서버가 연결되어 있어야 합니다.

POST /api/architect/revise
POST /api/architect/validate_yaml
GET  /api/architect/revisions?workflow_kref=kref://...
POST /api/architect/republish

수정안 제안

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

{
  "workflow_kref": "kref://Revka/Workflows/daily-report.workflow",
  "operations": [ { "op": "add_step", "step": { "id": "review", "action": "review" } } ],
  "rationale": "Add a review gate before publishing."
}

필드	필수 여부	설명
`workflow_kref`	필수	수정할 워크플로우 아이템.
`operations`	필수	operator의 `revise_workflow` 도구에 그대로 전달되는 비어 있지 않은 작업 객체 배열. 도구가 작업 형식을 정의하고 검증합니다.
`rationale`	선택	수정안에 첨부되는 설명.

revise_workflow의 구조화된 결과가 변경 없이 반환됩니다.

YAML 제안 검증

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

{
  "yaml": "<proposed workflow yaml>",
  "base_yaml": "<current yaml, optional>",
  "intent_summary": "Add a review gate"
}

제안된 YAML을 LLM이 사용하는 것과 동일한 propose_workflow_yaml operator 도구를 통해 라우팅하여 { valid, errors, warnings, yaml, summary, added_step_ids, modified_step_ids, removed_step_ids }를 반환합니다. 검증만 수행하며 어떤 것도 저장하지 않습니다. 편집기는 채팅 폴백 경로에 이를 사용합니다. Architect가 도구 호출 대신 채팅에서 YAML을 내보낼 때, 클라이언트는 추출된 YAML을 여기에 게시하여 캔버스에 적용하기 전에 스키마 및 워크플로우 수준 검사를 통과하도록 합니다.

리비전 목록 조회

GET /api/architect/revisions?workflow_kref=kref://Revka/Workflows/daily-report.workflow
Authorization: Bearer <token>

편집기의 히스토리 스트립에서 사용하는 워크플로우 아이템의 리비전 히스토리 요약 { "revisions": [ { "kref": "...?r=N", "number": N, "created_at": "...", "tags": [...], "metadata": { ... } } ] }를 반환합니다.

재발행(되돌리기)

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

{ "revision_kref": "kref://Revka/Workflows/daily-report.workflow?r=2" }

이전 리비전에 published 태그를 다시 지정합니다. 아무것도 삭제하지 않고 워크플로우를 이전 리비전으로 되돌리는 UI 안전 방법입니다. published 태그는 하드코딩되어 있으므로 호출자는 이 라우트를 통해 임의의 태그 값을 설정할 수 없습니다. 성공 시 { "ok": true, "revision_kref": "..." }를 반환하고, 워크플로우 목록 캐시를 무효화하며, 편집기가 캔버스와 YAML을 새로 고치도록 workflow.revision.published 이벤트를 브로드캐스트합니다.

SSE 이벤트

워크플로우 상태 변경은 서버 전송 이벤트 스트림(GET /api/events)을 통해 대시보드 클라이언트에 푸시됩니다. 관련 이벤트 타입은 다음과 같습니다.

이벤트 `type`	발생 시점
`workflow.revision.published`	정의가 생성, 수정, 또는 재발행으로 되돌려질 때.
`human_approval_resolved`	실행의 승인 게이트가 승인 또는 거부될 때.
`workflow_retry`	실행 재시도가 요청될 때.
`workflow_cancel`	실행 취소가 요청될 때.

human_approval_resolved, workflow_retry, workflow_cancel은 run_id와 timestamp를 포함합니다. workflow.revision.published는 workflow_kref, revision_kref, revision_number, name, published_at, originating_session을 포함합니다. 전체 SSE 봉투 및 기타 이벤트 타입에 대해서는 실시간: WebSocket, SSE 및 Live Canvas를 참고하세요.

유효성 검사

워크플로우를 저장하거나 실행할 때 operator의 validate_workflow 도구를 통해 YAML을 검증하며, 이 도구는 6단계 검사를 수행합니다(중복 단계 ID, 의존성 참조, 순환 감지, 단계별 설정, 변수 참조, 트리거 필드). 실패 시 POST/PUT 정의와 POST /api/workflows/run/{name}은 400과 다음 형식의 본문을 반환합니다.

{
  "error": "Workflow validation failed: ...",
  "valid": false,
  "errors": [ ... ],
  "warnings": [ ... ]
}

인프라 오류로 인해 유효성 검사를 실행할 수 없는 경우(예: operator가 일시적으로 연결 불가), 저장을 차단하는 대신 건너뜁니다(fail-open). 유효성 검사 규칙에 대한 자세한 내용은 워크플로우 YAML 레퍼런스를 참고하세요.

워크플로우 및 Architect API

인증

스토리지 동작 방식

워크플로우 정의

엔드포인트

정의 목록 조회

정의 생성

정의 수정

정의 폐기

정의 삭제

특정 리비전 조회

워크플로우 실행

엔드포인트

실행 상태

실행 목록 조회

단일 실행 조회

실행 트리거

인간 승인 게이트

실패한 실행 재시도

실행 중인 실행 취소

실행 삭제

대시보드 통계 엔드포인트

에이전트 활동 로그

Architect — AI 지원 워크플로우 수정

수정안 제안

YAML 제안 검증

리비전 목록 조회

재발행(되돌리기)

SSE 이벤트

유효성 검사

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조