본 문서는 영어 원본을 기계 번역한 것입니다. 번역본과 영어 원본 사이에 내용이 상충할 경우 영어 원본이 우선합니다. 영어 원본 보기

공개 API

Caiioo는 에이전트 실행, 도구 관리, 작업 예약 등 모든 기능을 프로그래밍 방식으로 제어할 수 있는 REST API를 제공합니다. 이 API는 데스크톱 앱과 브라우저 브리지를 구동하는 동일한 로컬 서버에서 작동합니다.

기본 URL: http://localhost:3847/v1

인증: 두 가지 인증 방식이 있으며, 두 방식 모두 설정의 API 토글을 통해 활성화해야 합니다.

외부 사용자용 (스크립트, 통합, curl): 설정 > API 액세스에서 API 액세스 토큰을 설정한 후, Bearer 토큰으로 사용하세요:

curl -H "Authorization: Bearer YOUR_API_TOKEN" http://localhost:3847/v1/providers

로컬 앱용 (자동): Caiioo 데스크톱 앱, 브라우저 확장 프로그램 및 모바일 앱은 기존 릴레이 인증 헤더(X-Relay-Auth)를 통해 자동으로 인증됩니다. 별도의 수동 설정이 필요 없으며, 앱이 백그라운드에서 이를 처리합니다.

설정 방법:

Caiioo 설정 > API 액세스를 엽니다.
공개 API 활성화 토글을 켭니다.
API 액세스 토큰을 설정합니다 (원하는 문자열을 입력하되, 비밀번호처럼 관리하세요).
모든 API 요청에 해당 토큰을 사용합니다.

API는 로컬 호스트 및 프라이빗 릴레이를 통해 사용할 수 있습니다. 현재 상태 및 설정 지침은 GET /v1/auth/info(인증 불필요)에서 확인하세요.

제공업체 및 모델

구성된 LLM 제공업체와 사용 가능한 모델을 확인합니다.

제공업체 목록:

GET /v1/providers

구성된 모든 제공업체 유형(Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten 등)을 기능 플래그(supportsVision, supportsToolCalling, supportsStreaming 등) 및 API 키 구성 여부와 함께 반환합니다.

제공업체별 모델 목록:

GET /v1/providers/anthropic/models

해당 제공업체의 모델 카탈로그를 반환합니다. 각 모델에는 id, displayName 및 사용 가능한 경우 contextLength가 포함됩니다.

전체 모델 통합 카탈로그:

GET /v1/models

구성된 모든 제공업체의 모델을 하나의 목록으로 병합합니다. API 키가 없는 제공업체는 건너뛰고 warnings에 나열됩니다.

에이전트

에이전트는 Caiioo의 핵심입니다. 각 에이전트는 하나의 모드이며, 자체 시스템 프롬프트, 도구, 변수 및 스킬을 가진 구성된 페르소나입니다.

모든 에이전트 목록:

GET /v1/agents

기본 제공 에이전트(쇼핑, 업무, 일반)와 직접 만든 커스텀 에이전트를 반환합니다. 각 에이전트에는 source: \"builtin\" 또는 source: \"custom\" 태그가 붙습니다.

커스텀 에이전트 생성:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"리서치 에이전트\",
    \"description\": \"웹을 검색하고 결과를 요약합니다\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"당신은 리서치 어시스턴트입니다. 항상 출처를 인용하세요.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

생성된 에이전트와 함께 201을 반환합니다. 동기화를 위해 벡터 클락이 자동으로 첨부됩니다.

에이전트 업데이트:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"리서치 에이전트\", \"description\": \"업데이트된 설명\" } }

기존 에이전트에 패치를 병합하고 벡터 클락을 올립니다. 기본 제공 에이전트는 403을 반환합니다(읽기 전용).

에이전트 삭제:

DELETE /v1/agents/my-research-agent

톰스톤을 통해 소프트 삭제됩니다(기기 간 동기화됨). 204를 반환합니다.

에이전트 실행

이것은 핵심 기능입니다 — 메시지를 처리하기 위해 에이전트를 호출합니다.

동기 모드 (Synchronous Mode)

전체 응답이 올 때까지 기다립니다:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "오늘 파리 날씨는 어때?" },
  "mode": "sync"
}

에이전트가 완료되면 { content, usage, status: "completed" }와 함께 200을 반환합니다. 에이전트 오류 발생 시 { error, status: "error" }와 함께 500을 반환합니다.

비동기 모드 (Asynchronous Mode)

실행 후 즉시 반환 — 시간이 오래 걸리는 작업에 유용합니다:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "재생 에너지 트렌드에 대한 2000단어 분석 보고서를 작성해줘" },
  "mode": "async"
}

즉시 { runId, threadId, status: "running" }와 함께 202를 반환합니다.

상태 폴링:

GET /v1/runs/{runId}

{ run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }를 반환합니다. 상태는 running, completed, error, cancelled 중 하나입니다.

실시간 이벤트 스트리밍 (SSE):

GET /v1/runs/{runId}/events

GENERATION_STARTED, STREAMING_CONTENT, 도구 호출, 서브 에이전트 활동 및 최종 이벤트(GENERATION_COMPLETE, GENERATION_ERROR, GENERATION_CANCELLED) 등 모든 에이전트 이벤트를 발생 즉시 text/event-stream으로 반환합니다. 스트림은 최종 이벤트 이후 종료됩니다.

실행 취소:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } }를 반환합니다.

Threads

Threads는 대화입니다. 모든 에이전트 실행은 Thread 내에서 발생하며, Thread는 세션 간에 유지됩니다. API를 통해 프로그래밍 방식으로 Thread를 나열, 읽기, 생성 및 관리할 수 있습니다.

모든 Thread 나열 (메타데이터만):

GET /v1/threads

성능을 위해 메시지가 제외된 현재 프로필의 Thread들을 반환합니다. 각 Thread에는 id, title, createdAt, updatedAt, modeId, archived 및 사용 통계가 포함됩니다.

전체 메시지가 포함된 Thread 가져오기:

GET /v1/threads/{id}

messages 배열(모든 사용자 메시지, 어시스턴트 응답, 도구 호출 및 도구 결과)을 포함한 전체 Thread를 반환합니다.

메시지만 가져오기:

GET /v1/threads/{id}/messages

messages 배열만 반환합니다. 대화 내용만 필요할 때 전체 Thread 객체보다 가볍게 사용할 수 있습니다.

Thread 생성:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

새 Thread와 함께 201을 반환합니다. 기본적으로 API는 앱의 활성 Thread를 전환하지 않습니다. 전환을 원할 경우 본문에 "setActive": true를 전달하십시오. 새 Thread는 즉시 사이드바에 표시됩니다(WebSocket 브로드캐스트를 통해).

Thread 업데이트:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

업데이트 가능한 필드: title, modeId, archived, lastUsedModel. 변경 사항은 실시간으로 사이드바에 브로드캐스트됩니다.

Thread 삭제:

DELETE /v1/threads/{id}

Thread를 소프트 삭제(동기화를 위한 tombstone 처리)합니다. 204를 반환합니다. 삭제된 Thread는 휴지통으로 이동하며 휴지통을 비우기 전까지 복구할 수 있습니다.

활성 Thread:

GET /v1/threads/active            # { threadId } 반환
PUT /v1/threads/active            # 본문: { "threadId": "..." }

휴지통 관리:

GET /v1/threads/trash/count       # { count } 반환
POST /v1/threads/trash/empty      # { deletedCount, protectedCount } 반환

보호된 Thread(데이터 보존 토글을 통해 유지됨)는 휴지통 비우기에서 제외됩니다.

API를 통한 대화 이어가기: 기존 Thread에 후속 메시지를 보내려면 Thread ID와 함께 POST /v1/runs를 사용하십시오:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

에이전트는 Thread의 전체 대화 기록을 참조합니다.

첨부 파일

첨부 파일은 스레드에 연결된 파일(스크린샷, PDF, 문서, 업로드된 이미지, 생성된 아티팩트 등)입니다. API를 통해 이를 나열, 업로드, 다운로드 및 관리할 수 있습니다.

모든 첨부 파일 목록 조회 (메타데이터만):

GET /v1/attachments

현재 프로필의 첨부 파일 메타데이터를 반환합니다. 용량이 큰 필드(dataUrl, extractedContent, extractedImages)는 제외되므로, 해당 데이터가 필요한 경우 상세 또는 콘텐츠 엔드포인트를 사용하세요.

특정 스레드의 첨부 파일 목록 조회:

GET /v1/threads/{threadId}/attachments

첨부 파일 메타데이터 조회:

GET /v1/attachments/{id}

extractedContent(OCR 텍스트, 파싱된 마크다운), contentType, fileName, size 및 hasContent 플래그를 포함한 전체 메타데이터를 반환합니다. 원본 바이너리는 포함되지 않으며 /content 엔드포인트를 사용하세요.

첨부 파일 바이너리 다운로드:

GET /v1/attachments/{id}/content

올바른 Content-Type 및 Content-Disposition 헤더와 함께 원본 파일을 반환합니다. 다음과 같이 파일로 저장할 수 있습니다:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

첨부 파일 업로드:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "분기별 보고서",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl은 base64로 인코딩된 데이터 URL입니다. 새로운 첨부 파일 ID와 함께 201을 반환합니다. 첨부 파일은 지정된 스레드에 연결됩니다.

첨부 파일 메타데이터 업데이트:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "업데이트된 설명", "fileName": "new-name.pdf" }

첨부 파일 삭제:

DELETE /v1/attachments/{id}

툼스톤을 통해 소프트 삭제합니다. 204를 반환합니다.

MCP Servers

에이전트에게 외부 도구 및 데이터 소스에 대한 접근 권한을 부여하는 MCP (Model Context Protocol) 서버 연결을 관리합니다.

구성된 서버 목록 조회:

GET /v1/mcp-servers

현재 프로필의 모든 MCP 서버 구성을 반환합니다. 민감한 필드(authToken, env, credentialId)는 응답에서 제외됩니다.

서버 구성 조회:

GET /v1/mcp-servers/{id}

새 MCP 서버 추가:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

원격 HTTP 서버의 경우 "command" 대신 "url"을 사용하세요:

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

서버 업데이트:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

서버 활성화/비활성화:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

서버 삭제:

DELETE /v1/mcp-servers/{id}

Process Management

로컬 (stdio) MCP 서버의 경우, 서버 프로세스를 직접 관리할 수 있습니다.

실행 중인 프로세스 목록 조회:

GET /v1/mcp-servers/processes

pid, startedAt, running 상태를 포함하여 실행 중인 서버 프로세스를 반환합니다.

서버 시작:

POST /v1/mcp-servers/{id}/start

서버 구성에서 command/args/env를 읽어 프로세스를 생성합니다. 프로세스 상태를 반환합니다.

서버 중지:

POST /v1/mcp-servers/{id}/stop

서버 프로세스를 정상적으로 종료합니다 (SIGTERM 후 실패 시 SIGKILL 사용).

JSON-RPC 메서드 직접 호출:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

서버에 원시 JSON-RPC 2.0 요청을 보내고 결과를 반환합니다. 디버깅이나 도구 API를 통해 노출되지 않은 메서드를 호출할 때 유용합니다.

도구 및 툴킷

웹 브라우징, 검색, 캘린더, Gmail, Slate 등 에이전트가 사용하는 도구를 탐색하고 호출합니다.

툴킷 목록 조회 (그룹화):

GET /v1/toolkits

카테고리별(생산성, 검색, 유틸리티 등)로 그룹화된 내장 도구와 연결된 MCP 서버를 별도의 툴킷으로 반환하며, 각 액션 목록을 포함합니다.

모든 도구 목록 조회 (평면):

GET /v1/tools
GET /v1/tools?source=embedded   # 내장 도구만
GET /v1/tools?source=mcp        # MCP 서버 도구만

입력 스키마를 포함한 도구 상세 정보:

GET /v1/tools/calculator

도구의 입력 매개변수에 대한 JSON Schema를 반환하여 호출 전 유효성을 검사할 수 있습니다.

도구 직접 호출:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" } }

{ result }를 반환합니다. 입력값은 도구 스키마에 따라 검증되며, 유효하지 않은 경우 상세 내용과 함께 422를 반환합니다. 원격 MCP 도구는 에이전트 서브프로세스 전송이 필요하므로 /v1/runs를 사용하라는 안내와 함께 501을 반환합니다.

커넥터

Google, Microsoft, GitHub, Notion, Slack 등 OAuth 통합을 관리합니다.

사용 가능한 통합 탐색:

GET /v1/connectors/catalog

등록된 모든 OAuth 제공자의 이름, 카테고리 및 기본 스코프를 반환합니다.

연결된 계정 목록 조회:

GET /v1/connectors

현재 프로필의 활성 연결을 반환합니다. 토큰은 절대 노출되지 않으며 메타데이터(제공자, 이메일, 상태, 스코프, 타임스탬프)만 제공됩니다.

연결 상태 확인:

POST /v1/connectors/{id}/test

{ health: { status, isTokenExpired, canRefresh } }를 반환합니다.

연결 제거:

DELETE /v1/connectors/{id}

새 연결을 생성하려면 앱 UI 또는 /auth/* 경로를 통한 대화형 OAuth 흐름이 필요합니다.

트리거

일일 브리핑, 주간 보고서, 간격 기반 모니터링 등 에이전트가 자동으로 실행되도록 예약합니다.

트리거 목록 조회:

GET /v1/triggers

예약된 트리거 생성:

POST /v1/triggers
Content-Type: application/json

{
  "name": "아침 브리핑",
  "prompt": "읽지 않은 이메일과 오늘 일정을 요약해줘",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

지원되는 일정 유형:

{ "type": "interval", "minutes": 60 } — N분마다 (최소 15, 최대 1440)
{ "type": "daily", "time": "09:00" } — 매일 특정 시간
{ "type": "weekly", "day": "mon", "time": "09:00" } — 매주
{ "type": "weekdays", "time": "08:30" } — 월요일부터 금요일까지
{ "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — 특정 요일
{ "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — 매월
{ "type": "manual" } — API를 통해 실행할 때만

트리거 수동 실행:

POST /v1/triggers/{id}/fire

결과 실행에 대한 threadId와 함께 202를 반환합니다.

업데이트 또는 삭제:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

웹훅

웹훅 트리거를 사용하면 외부 서비스(CI/CD, 모니터링, 폼 빌더)가 HTTP를 통해 에이전트 실행을 트리거할 수 있습니다.

웹훅 트리거 생성:

POST /v1/triggers
Content-Type: application/json

{
  "name": "배포 훅",
  "prompt": "배포가 발생했습니다: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

webhookSecret 및 webhookPath와 함께 201을 반환합니다. 페이로드 서명에 필요하므로 비밀 키를 안전하게 보관하세요.

웹훅 전송:

# 원본 요청 본문의 HMAC-SHA256 계산
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

웹훅 엔드포인트는 Bearer 인증이 필요하지 않으며 대신 HMAC 검증을 사용합니다. 디스패치된 실행의 threadId와 함께 202를 반환합니다. 트리거 프롬프트의 {{webhook.body}} 자리표시자는 원본 요청 본문으로 대체됩니다.

커스텀 함수

에이전트가 호출할 수 있는 고유한 도구를 만듭니다. 함수는 JavaScript 또는 Python으로 작성되며 샌드박스에서 실행됩니다.

함수 목록 조회:

GET /v1/functions

함수 생성:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "키와 몸무게로 체질량 지수(BMI) 계산",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

JavaScript 함수는 input을 받아 결과를 반환해야 합니다. Python 함수는 result 변수를 설정합니다:

# Python 예시
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

함수 직접 실행:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

보안: JavaScript는 Node의 vm 샌드박스에서 실행됩니다(파일 시스템 또는 네트워크 액세스 불가, 10초 타임아웃). Python은 30초 타임아웃이 있는 서브프로세스로 실행됩니다. 둘 다 실행 전 입력을 검증합니다.

업데이트 또는 삭제:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

워크플로우

여러 에이전트를 DAG(방향성 비순환 그래프)로 오케스트레이션합니다. 가능한 경우 단계를 병렬로 실행하고, 이전 단계의 출력을 다음 단계의 입력으로 전달합니다.

워크플로우 그래프 검증:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "재생 에너지 트렌드 조사" },
      { "id": "analyze", "agentId": "general", "prompt": "경쟁사 가격 조사" },
      { "id": "report", "agentId": "general", "prompt": "다음 내용을 결합하여 보고서 작성: {{outputs.research}} 및 {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

{ valid: true/false, errors: [...] }를 반환합니다. 순환 참조, 중복 ID 및 누락된 종속성 참조를 확인합니다.

워크플로우 실행:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "재생 에너지 트렌드 조사" },
      { "id": "summarize", "agentId": "general", "prompt": "요약: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

{ status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }를 반환합니다.

독립적인 노드(공유 종속성 없음)는 병렬로 실행됩니다. 노드 프롬프트의 {{outputs.nodeId}} 자리표시자는 지정된 상류 노드의 콘텐츠 출력으로 대체됩니다. 각 노드는 전체 에이전트 실행이므로 도구 사용, 웹 브라우징 및 대상 에이전트의 모든 기능을 사용할 수 있습니다.

지식 베이스

문서를 에이전트가 참조할 수 있는 검색 가능한 컬렉션으로 구성합니다.

지식 베이스 목록 조회:

GET /v1/knowledge/bases

지식 베이스 생성:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "연구 논문" }

새로운 베이스 ID와 함께 201을 반환합니다.

지식 베이스에 문서 업로드:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "2026년 재생 에너지 트렌드"
}

dataUrl 필드는 base64로 인코딩된 데이터 URL입니다. 문서 메타데이터와 함께 201을 반환합니다.

지식 베이스 내 문서 목록 조회:

GET /v1/knowledge/bases/{id}/documents

지식 베이스 내 검색:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "재생 에너지" }

파일 이름과 설명을 기반으로 일치하는 문서를 반환합니다. 시맨틱(벡터) 검색은 향후 릴리스에서 제공될 예정입니다.

문서 또는 지식 베이스 삭제:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

에이전트 내보내기 및 가져오기

에이전트를 기기, 팀 또는 커뮤니티 허브 간에 이동 가능한 패키지로 공유하세요.

에이전트 내보내기:

POST /v1/agents/{id}/export

에이전트 정의, 도구 요구 사항, 커넥터 요구 사항 및 트리거 템플릿이 포함된 JSON 패키지를 반환합니다. 동기화 메타데이터는 제거되어 깨끗하고 독립적인 청사진이 됩니다.

에이전트 가져오기:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"리서치 에이전트\", \"description\": \"팀에서 공유함\" },
      \"defaultSettings\": { \"systemPrompt\": \"당신은 리서치를 수행합니다.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

설치된 에이전트와 함께 201을 반환합니다. 기본 제공 또는 기존 에이전트와 ID가 충돌하면 409를 반환합니다.

오류 처리

API는 표준 HTTP 상태 코드를 사용합니다.

코드	의미
`200`	성공
`201`	생성됨
`202`	수락됨 (비동기 작업 시작됨)
`204`	삭제됨 (콘텐츠 없음)
`400`	잘못된 요청 — `error` 필드에서 상세 내용 확인
`401`	인증되지 않음 — 세션 비밀 키 누락 또는 유효하지 않음
`403`	금지됨 — 예: 기본 제공 에이전트 수정 시도
`404`	찾을 수 없음
`409`	충돌 — 예: 에이전트 ID가 이미 존재함
`422`	유효성 검사 오류 — 입력이 도구 스키마와 일치하지 않음
`500`	서버 오류 — `error` 필드 확인
`501`	구현되지 않음 — 기능은 존재하나 이 방식으로는 사용 불가
`503`	서비스 사용 불가 — 저장소 또는 제공자가 준비되지 않음

모든 오류 응답에는 { "error": "사람이 읽을 수 있는 메시지" }가 포함됩니다.

빠른 시작 예시

에이전트를 생성하고 실행한 뒤 결과를 스트리밍하는 전체 워크플로우입니다.

# 1. 커스텀 에이전트 생성
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "모든 입력을 3개의 불렛 포인트로 간결하게 요약하세요.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. 비동기로 실행
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "https://ko.wikipedia.org/wiki/인공지능 요약해줘" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. 이벤트 스트리밍
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. 공유를 위해 에이전트 내보내기
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.