Playground API

/api/playground/v1은 Studio Playground의 첫 버전드 공개 계약입니다. Studio가 loopback에서 실행될 때만 사용하며 Agent runtime의 /api/v1/*와는 다른 표면입니다.

기존 Studio의 무버전 /api/runtime, /api/project, /api/save 계약은 v0.5.0에서 바뀌지 않습니다. 새 자동화는 이 페이지의 versioned prefix를 사용하세요. 기존 Studio 표면도 향후 호환 기간을 두고 점진적으로 versioned 경로를 제공할 예정입니다.

Endpoint

Method	Path	성공
`GET`·`POST`	`/api/playground/v1/sessions`	목록 · `201` session
`DELETE`	`/api/playground/v1/sessions/{session_id}`	session과 orphan blob 삭제
`GET`·`POST`	`/api/playground/v1/sessions/{session_id}/runs`	목록 · `202 {"run_id", "status"}`
`GET`·`DELETE`	`/api/playground/v1/runs/{run_id}`	상세 · 명시적 취소
`POST`	`/api/playground/v1/runs/{run_id}/resume`	`202` child run
`POST`	`/api/playground/v1/runs/{run_id}/rerun`	`202` 새 context run
`GET`	`/api/playground/v1/runs/{run_id}/events`	SSE replay + live
`GET`	`/api/playground/v1/compare?left=...&right=...`	구조적 비교
`GET`	`/api/playground/v1/composer-schema`	live 입력 제안
`GET`	`/api/playground/v1/source-targets/{node_id}`	AST source 위치
`POST`	`/api/playground/v1/bundles/export`	bundle JSON
`POST`	`/api/playground/v1/bundles/import`	`201` 새 ID mapping

run 생성, resume, rerun은 요청 안에서 비즈니스 실행을 기다리지 않고 항상 202로 server-owned background run ID를 돌려줍니다.

{
  "parts": [
    {"kind": "text", "text": "승인 상태를 확인해 줘"},
    {
      "kind": "data",
      "data": {"schema": "approval.v1", "requestId": "R-1"}
    }
  ],
  "metadata": {"userId": "user-1"},
  "changed_files": ["app/nodes.py"],
  "revision": "optional-client-revision"
}

changed_files는 프로젝트 안의 상대 경로만 허용합니다. 프로젝트 전체에서 이미 활성 run이 있으면 다음 응답을 반환합니다.

{
  "detail": {
    "error": "active_run_conflict",
    "active_run_id": "run_..."
  }
}

HTTP status는 409 Conflict입니다.

Run 상태

고정 상태는 다음 여덟 개입니다.

queued
preparing
running
input_required
completed
failed
cancelled
interrupted

세부 원인은 reason에 둡니다. 예를 들어 runtime_unavailable, runtime_restarted, project_validation, user_cancelled, studio_shutdown입니다. 클라이언트가 새로운 reason을 허용할 수 있게 작성하세요.

input_required는 이번 run의 terminal 상태이지만 session의 대화는 끝나지 않았습니다. /resume이 같은 context_id·task_id를 가진 새 child run을 만듭니다. /rerun은 input part를 복제하고 새 context_id를 사용합니다.

Tagged part

저장되는 입출력은 다음 discriminator를 사용합니다.

`kind`	핵심 필드
`text`	`text`
`data`	JSON object인 `data`
`file`	local은 `sha256`·`size`, external은 `uri`·`availability`·`replay`
`status`	`status`, 선택 `reason`
`error`	`message`, 선택 `code`

inline file은 content-addressed store로 옮긴 뒤 DB에는 hash, 이름, MIME, size, source만 저장합니다. URI file은 다운로드하지 않습니다.

DataPart의 name은 A2A wire 필드가 아닙니다. 입력 계약의 name은 Studio 탭을 구분하는 표시이며 사용자가 입력하지 않습니다. schema 식별자가 필요한 계약은 별도 part 필드가 아니라 data.schema에 넣습니다. Flow composer는 선언된 DataContract.schema를 JSON 초안에 자동으로 포함합니다.

SSE replay

GET /runs/{run_id}/events는 SQLite event seq를 SSE id로 사용합니다.

id: 42
event: run.phase
data: {"seq":42,"run_id":"run_...","kind":"run.phase",...}

재연결할 때 Last-Event-ID: 42를 보내거나 ?after=42를 사용하면 그 다음 sequence부터 replay한 뒤 live event로 이어집니다. 두 값이 모두 있으면 더 큰 cursor를 사용합니다. 연결 종료는 run을 취소하지 않습니다.

대표 event name은 run.status, run.phase, run.output, output.delta, trace, diagnostic입니다. Studio는 output.delta의 text를 순서대로 이어 붙여 진행 중인 run에만 표시하고, run이 종료되면 저장된 최종 part로 대체합니다. token delta마다 screen reader announce를 유도하지 않도록 announce는 phase 전환만 합니다.

run.phase의 payload는 phase·state 위에 그 단계의 detail을 그대로 병합합니다. 실패한 complete phase는 reason과, 원인이 runtime_unavailable일 때 recommended_run_command를 함께 담습니다.

evaluation.result trace는 run의 scores에 반영됩니다. score 외의 항목은 모두 선택이며 payload에 있을 때만 저장합니다.

key	의미
`reason`	evaluator가 남긴 근거
`passStatus`	evaluator 자신의 합격 판정. Playground는 이 값을 만들지 않습니다
`scope`·`node`	평가가 붙은 위치. `node`가 있으면 Studio가 그 노드의 평가 선언으로 이동할 수 있습니다
`duration_ms`	그 evaluator가 소비한 시간. 보고하지 않는 runtime의 기록에는 없습니다

이 목록은 앞으로도 추가만 합니다. 새 key를 모르는 client는 무시하면 되고, 보내지 않는 runtime의 기존 기록도 그대로 유효합니다.

Compare

compare 응답에는 다음 항목이 있습니다.

left/right status와 duration, duration delta
text 원문과 unified diff
DataPart JSON의 path별 add/remove/replace
FilePart metadata·URI·hash 비교
evaluator별 left/right score와 delta

automatic_verdict는 항상 null입니다. v1은 자동 pass/fail 정책을 정의하지 않습니다.

Bundle v1

export body는 선택할 session_ids 또는 run_ids를 받습니다.

{
  "session_ids": ["ses_..."],
  "run_ids": ["run_..."]
}

응답의 format은 정확히 "llamon.playground.bundle/1"입니다. sessions, runs, events, blobs를 포함하며 blobs는 SHA-256을 key로 하고 bytes_base64와 size를 가집니다.

import는 {"bundle": <export-response>} 또는 bundle object 자체를 받습니다. 모든 ID 관계와 blob hash/size를 durable write 전에 검증하며 새 ID mapping을 반환합니다. 지원 버전보다 새로운 local SQLite schema는 수정하지 않고 409 unsupported_database_version으로 거부합니다.

.env, capture token, 예약 metadata llamon.playground는 export하지 않습니다. 사용자 metadata는 redaction되지만 text/data/file 본문까지 자동 비식별화하지 않으므로 공유 전 검토해야 합니다.

사용 흐름과 Host 보안 경계는 Studio Playground를 참고하세요.