DOCS · API REFERENCE

외부 시스템 통합 API 명세

Vantisso를 이용한 자체 에이전트 애플리케이션을 개발하거나 기업의 IT 운영 포털/시스템이 Vantisso를 제어하고 관리하는 기능 구현 시 참조용 REST API 명세서이다.

최종 수정 · 2026년 7월 28일

API 호출 기본 구성

인증 및 인가 방식 이해

1 · 토큰 기반 인증

토큰은 Vantisso 운영자(operator)가 발급하며 발급된 토큰을 Bearer 헤더에 넣어서 전송한다. 로컬 개발 작업 중에는 인증을 끄고 토큰 없이 진행할 수 있는데 이때 operator 모드로 동작하게 된다.

curl -H "Authorization: Bearer $TOKEN" http://host:3000/whoami

{ "name": "acme-portal", "role": "user", "auth_disabled": false }

2 · 역할과 소유권 기반 인가

모든 API 호출은 다음과 같은 두 가지 기준에서 검사가 진행되는데 부여받은 역할이 해당 동작 수행을 허용받았는지와 접근하려는 대상에 대한 접근 권한을 갖고 있는지를 확인한다.

3 · 상황 별 토큰 사용 가이드

4 · 단일 에이전트 생성시 주의 사항

5 · 에러 코드 설명

6 · 멀티테넌트 격리 레시피

1. 테넌트당 user 토큰 하나를 발급한다. 여기서 테넌트는 고객사, 포털 로그인 사용자, 프로젝트 워크스페이스 등 다양하게 격리하고 싶은 개별 단위를 의미하며 Vantisso는 각 테넌트를 하나의 토큰에 매핑하고 있다. 참고로 expires 필드를 이용해서 테넌트에 TTL을 걸 수도 있다.
2. 각 테넌트가 자기 그룹을 만들고 그 안에서 에이전트들을 구동한다. 그 그룹에 속한 모든 에이전트들은 전부 동일한 owner id를 상속하게 된다.
3. 이렇게 하면 서버의 호스트가 자동으로 목록 조회 시 자기 테넌트에 해당하는 것만 보이게 강제하고 테넌트가 소유하지 않은 에이전트로 행위 요청을 하면 404 에러 발생시켜 막는다.

단일 에이전트 실행

에이전트 그룹을 생성하지 않고 에이전트 하나만 생성해서 작업을 실행하려면 무조건 operator 토큰으로 에이전트를 실행할 VM을 생성해야 한다.

1. VM 생성 : {"profile":"…"} 옵션을 통해 커스터마이징된 sizing/model/system-prompt를 적용할 수 있다. 이 옵션을 생략하면 기본 프로파일이 자동 적용된다.

curl -sX POST http://host:3000/vms \
  -H "Authorization: Bearer $OP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile":"support-agent"}'

201 Created
{
  "vm_id": "vm-1720982400000000000",
  "guest_ip": "10.0.1.5",
  "runtimed_url": "http://10.0.1.5:8080",
  "profile": "support-agent",
  "provider": "google",
  "model": "gemini-2.0-flash",
  "runtimed_token": "…"
}

이 호출은 요청 후 에이전트가 준비될 때까지 블록된다.(통상 1초 이내, 최대 60초까지 대기) runtimed_token은 한 번만 반환되며 재발급되지 않는다. 다만 컨트롤 플레인 프록시가 이 토큰은 중앙 관리하면서 필요 시 각 VM에 자동 주입하기 때문에 개발자가 직접 쓸 일은 드물다. VM 생성 요청 시 디스크가 부족하면 507 에러가 반환되고, 유효 기간이 만료되면 403 trial_expired 에러가 반환된다.

2. 태스크 실행 : 컨트롤 플레인이 관리하고 있는 토큰을 제공받아 프롬프트가 에이전트로 자동 전달된다. 에이전트는 한번에 하나의 태스크를 처리하는데 처리 중이면 503을 회신한다.

curl -sX POST http://host:3000/vms/$VM_ID/tasks \
  -H "Authorization: Bearer $OP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize ticket INC-4821 and propose a resolution."}'

{ "output": "…the agent's final answer…", "error": "" }

• 멀티턴 지원 - "session": 사용자 제공 ID를 넘겨 한 대화 스레드를 여러 호출에 걸쳐 이어갈 수 있게 한다. 세션 정보는 VM 내부 에이전트 런타임 프로세스의 메모리에 저장되며 VM 별로 완전히 독립된 네임스페이스를 갖는다. 이 세션 ID는 토큰과는 달리 컨트롤 플레인이 관리하지 않고 패스스루한다.
• 스트리밍 지원 - ?stream=1로 설정하면 NDJSON 형식으로 데이터가 송출된다.

3. VM 소멸 : VM·네트워크·디스크가 자동으로 해제된다.

curl -sX DELETE http://host:3000/vms/$VM_ID -H "Authorization: Bearer $OP_TOKEN"

에이전트 팀 단위 운영

Vantisso는 에이전트를 팀 단위로 운영할 수 있도록 기능을 제공한다. 에이전트 그룹을 생성하고 해당 그룹 아래에 생성되는 에이전트들은 팀 단위로 협업하게 만들 수 있다.

1. 에이전트 그룹 생성 : 에이전트 그룹을 생성할 때 테넌트 토큰은 user 계열과 operator 계열 모두 사용 가능하다. 다만 user 계열 토큰 사용 시에는 Owner ID가 부여되고 해당 정보가 그룹에 속한 모든 에이전트들에게 전파되어 그룹의 소유권을 명확히 하게 된다. 반면에 operator 계열 토큰으로 생성한 그룹은 특정 테넌트에 귀속되지 않는 공유 자원으로 취급된다. Body에 정의하는 roles에 정의된 역할 별로 에이전트 VM 인스턴스가 생성된다. 이때 각 에이전트 VM이 할당받는 vCPU 수와 메모리 용량은 각 역할 별로 미리 정의된 자원 프로파일 정보를 참조하여 결정된다.

curl -sX POST http://host:3000/groups \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "task": "Draft the release notes for v1.4",
        "roles": ["orchestrator","writer","reviewer"],
        "max_agents": 5
      }'

201 Created
{
  "group_id": "group-1720982500000000000",
  "task": "Draft the release notes for v1.4",
  "agents": [
    { "agent_id": "orchestrator-1", "role": "orchestrator", "profile": "orchestrator",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.6:8080", "status": "ready" },
    { "agent_id": "writer-1", "role": "writer", "profile": "writer",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.7:8080", "status": "ready" },
    { "agent_id": "reviewer-1", "role": "reviewer", "profile": "reviewer",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.8:8080", "status": "ready" }
  ],
  "runtimed_tokens": { "orchestrator-1": "…", "writer-1": "…", "reviewer-1": "…" },
  "feed_url": "/groups/group-…/feed",
  "post_url": "/groups/group-…/post"
}

에이전트 별로 지정되는 ID는 위의 예시 응답에서 보는 것처럼 역할 이름과 인덱스 번호로 구성된다.(writer-1, writer-2, …) runtimed_tokens는 실제 에이전트와 통신하는데 사용되는 인증 토큰으로서 에이전트 생성 시 한 번만 응답 메시지에 실려 반환된다.

2. 태스크 실행 : 그룹에 속하는 단일 에이전트를 대상으로 프롬프트를 보낼 때는 vm_id를 이용해서 POST /vms/{id}/tasks) 방식으로 전달하며, 프롬프트를 그룹 내 전체 에이전트들에게 팬아웃하는 것도 가능한데 아래 예시와 같이 브로드캐스트 API 엔드포인트를 이용한다.

curl -sX POST http://host:3000/groups/$GID/broadcast \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" -d '{"body":"Status check: where are we?"}'

3. 에이전트 그룹 소멸 : 에이전트 그룹을 소멸시키면 해당 그룹에 속한 모든 에이전트 VM들도 함께 소멸된다.

curl -sX DELETE http://host:3000/groups/$GID -H "Authorization: Bearer $TENANT_TOKEN"

대화 세션 보존

실행 중의 대화 세션은 각 VM에 할당된 RAM에만 저장되기 때문에 VM이 종료되는 상황이 발생하면 세션도 함께 사라지게 된다. Vantisso는 에이전트의 대화 세션을 VM 종료 시 스냅샷 형태로 호스트에 persistent하게 저장하는 기능을 통해 VM 재기동 등의 상황에서도 에이전트의 대화 세션을 유지할 수 있게 구현되어 있다. 이것을 Vantisso에서는 Transcript 기능이라고 정의한다.

Transcript 레코드 예시:

{
  "schema_version": 1,
  "session": "INC-4821",
  "vm_id": "vm-…",
  "group_id": "group-…",
  "agent_id": "writer-1",
  "owner": "acme-portal",
  "profile": "support-agent",
  "title": "Summarize ticket INC-4821",
  "turns": [
    { "role": "user", "text": "Summarize ticket INC-4821…" },
    { "role": "assistant", "text": "…" }
  ],
  "saved_at": "2026-07-15T09:12:00Z"
}

에이전트 팀 구성 메타데이터

Vantisso 기반 커스텀 에이전트 팀 구성 및 관리 UI를 개발할 때 필요한 핵심 정보를 제공하는 API 엔드포인트는 다음과 같다.

프롬프트 응답 스트리밍

POST /vms/{id}/tasks?stream=1 호출은 프롬프트 처리에 대한 응답을 단일 버퍼 객체에 모두 담아서 한번에 리턴하는 대신 줄 구분 JSON(NDJSON) 방식을 이용해 한 줄당 한 프레임으로 반환하게 한다. 반환되는 프레임 형식은 다음 예시에서 보는 것과 같이 세 가지 타입을 갖는다.

{ "type": "progress", "text": "running shell: grep -n …" }
{ "type": "token",    "text": "The " }
{ "type": "token",    "text": "root cause " }
{ "type": "result",   "output": "…final answer…", "error": "" }

• type: "progress" — 에이전트 루프 수행, 툴 호출 시 정해진 스텝마다 전송되며 text 필드가 비어 있는 프레임이 보내지기도 하는데 이는 하트비트 역할을 수행하는 프레임이다. LLM의 접속 속도 제안에 따른 백오프와 같은 재시도 안내 정보도 이 프레임을 이용하여 전달된다.
• type: "token" — 앞에서 설명한 프로파일의 라이브 토큰 스트리밍이 켜진 경우에만 출력 텍스트의 증분이 프레임으로 전달되며 이것들을 순서대로 이어 붙이면 LLM 응답 출력의 전체가 재구성된다.
• type: "result" — 스트림당 정확히 마지막에 한번 전달되며 이 마지막 프레임만 읽어도 버퍼링된 객체를 그대로 복원할 수 있다. error 필드가 비어 있으면 성공, 특정 내용으로 채워져 있으면 실패이다.

에러 코드 요약

• 에러 전송 형식 : {"error":"…"} 형식의 JSON 객체로 통일되어 있다.

GET /license
→ {
  "type":       "evaluation",           // or "commercial"
  "status":     "active",               // "active" | "grace" | "expired"
  "started_at": "2026-07-01T00:00:00Z",
  "expires_at": "2026-07-31T00:00:00Z",
  "days_left":  21,
  "enforced":   true
}