Jenova 에이전트 API 참조

기본 URL: https://api.jenova.ai/v1

인증: Authorization 헤더에 Bearer 토큰 사용

목차

• 개요
• 빠른 시작
• 핵심 개념
• 인증
• API 엔드포인트
  • 메시지 API
  • 세션 API
  • 작업
  • 크레딧
  • 에이전트 API
  • 모델
  • 문서
• 스트리밍 (SSE)
• MCP 서버 통합
• 결제
• 속도 제한
• 오류 처리
• 페이지네이션
• 현지화
• 개인정보 보호 및 데이터
• 지원

개요

기반 스택을 직접 구성하지 않고도 프로덕션 수준의 AI 에이전트를 구축하고 실행할 수 있습니다. Jenova 에이전트 API는 모든 핵심 기능을 단일 관리형 서비스로 통합합니다:

완전한 에이전트 스택

• 에이전트 오케스트레이션: 통합 오케스트레이션 레이어가 복잡한 워크플로우 전반에서 모델, 도구, 메모리, 검색을 조율합니다.
• 메모리 및 컨텍스트: 모든 세션에 무제한 대화 메모리와 컨텍스트가 기본 내장되어 있습니다. 외부 상태 관리가 필요하지 않습니다.
• 도구 및 MCP: 플랫폼 네이티브 도구와 임의의 원격 MCP 서버에 대해 무제한 도구 통합을 즉시 사용할 수 있습니다.
• 모든 모델 사용 가능: OpenAI, Anthropic, Google, xAI, Qwen 등 다양한 모델을 하나의 통합으로 에이전트에 활용할 수 있습니다.
• 완전 관리형 스토리지: 내장 RAG를 갖춘 관리형 관계형 및 벡터 데이터베이스입니다. 인프라를 프로비저닝하거나 확장할 필요가 없습니다.
• 프로덕션 등급: 수십만 명의 사용자가 사용 중입니다. 완전 관리형 인프라와 안정적인 API로 프로덕션 트래픽에 맞게 구축되었습니다.

빠른 시작

1. API 키 받기

www.jenova.ai/platform의 개발자 대시보드에서 API 키를 생성합니다. 키는 jnv_sk_* 형식을 사용하며 Bearer 토큰으로 전달됩니다.

2. 에이전트 선택 또는 생성

플랫폼에서 사전 구축된 에이전트를 선택하거나, 대시보드에서 지침, 모델 설정, 지식 베이스 파일, 도구, MCP 서버를 지정하여 커스텀 에이전트를 생성합니다.

3. 첫 메시지 보내기

세션을 생성하고 한 번의 호출로 메시지를 보냅니다:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

응답은 Server-Sent Events로 스트리밍되어 돌아옵니다:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

후속 요청을 위해 stream_started에서 session_id를 확보하세요. 동기식 JSON 응답에 대해서는 메시지 보내기를 참조하세요.

핵심 개념

에이전트

API를 통해 상호작용하는 AI 에이전트입니다. 각 에이전트는 API 호출에서 agent 값으로 사용되는 고유한 slug(예: my-support-agent)를 가집니다.

• 사전 구축: 플랫폼에 있는 기존 에이전트 중에서 선택합니다.
• 커스텀: 대시보드에서 지침, 모델, 지식 베이스, 도구, MCP 서버를 지정하여 직접 구성합니다.

세션

최종 사용자와 에이전트 간의 독립적인 대화 스레드입니다.

• 식별자: 접두사가 붙은 ID(예: ses_abc123)
• 범위: 동일한 에이전트와 최종 사용자에 대해 여러 세션이 존재할 수 있으며, 각 세션은 독립적인 대화 상태를 가집니다
• 수명 주기: 세션은 API를 통해 삭제되기 전까지 무기한 유지됩니다. 저장이 필요 없는 일회성 작업의 경우 ephemeral: true와 함께 POST /messages를 사용하세요
• 플랫폼 분리: API 세션은 Jenova 웹 앱의 대화와 별개입니다. 최종 사용자, 세션 기록, 결제는 API와 웹 앱 간에 독립적으로 관리됩니다.

메시지

메시지 엔드포인트가 반환하는 세션 대화 기록의 단일 항목입니다. 각 메시지에는 type("user" 또는 "agent")과 name을 포함하는 구조화된 from 객체와, 메시지 자체의 type이 포함됩니다:

• external - 채팅 콘텐츠로 표시되도록 의도된 대화 메시지입니다.
• internal - 실행 중 도구 호출이나 검색과 같은 에이전트 작업 단계를 나타내는 선택적 메시지입니다.

실행

메시지를 보낼 때 생성되는 단일 에이전트 실행입니다. 실행에는 run_id가 있으며, 활성 상태 동안 이벤트를 스트리밍할 수 있고, 하나 이상의 완료된 메시지를 생성합니다. 각 세션은 한 번에 하나의 활성 실행만 가질 수 있습니다.

최종 사용자

user 필드는 세션을 귀하의 애플리케이션 내 최종 사용자 범위로 지정합니다. 내부 사용자 ID나 UUID와 같은 안정적이고 불투명한 ID를 사용하세요. 애플리케이션에서 필요하지 않은 경우 이메일이나 기타 개인식별정보(PII)는 피하세요. 동일한 user 값으로 생성된 세션은 함께 그룹화되어 사용자별 세션 목록 조회가 가능해집니다.

user가 생략되면 세션은 귀하의 개발자 계정 범위로 지정되며, 이후 최종 사용자별로 필터링할 수 없습니다. 프로덕션에서는 user를 전달하세요.

기존 세션에 대한 요청의 경우 user는 선택적인 소유권 확인 용도로 사용됩니다. 값을 제공하는 경우, 세션 생성 시 사용된 user 값과 일치해야 합니다. 그렇지 않으면 API는 404 session_not_owned를 반환합니다. GET 및 DELETE 요청에서는 쿼리 파라미터로, POST 및 PATCH 요청에서는 JSON 본문에 담아 전달하세요.

인증

모든 요청은 Authorization 헤더에 Bearer 토큰을 포함하여 인증해야 합니다:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 키는 개발자 대시보드에서 생성됩니다.

User-Agent는 선택 사항입니다. SDK는 진단 목적으로 이 값을 설정할 수 있지만, API에서 필수로 요구하지는 않습니다.

키 형식: 키는 접두사 jnv_sk_로 시작하며 그 뒤에 base62로 인코딩된 무작위 문자열이 이어집니다.

제한: 개발자 계정당 최대 10개의 활성 API 키를 가질 수 있습니다.

API 엔드포인트

메시지 API

메시지 보내기는 주요 API 경로입니다. 첫 메시지에는 POST /messages를 사용하며, 이 요청은 하나의 요청으로 세션을 생성하고 실행을 시작합니다. 캡처된 session_id로 계속하는 경우에는 POST /sessions/{session_id}/messages를 사용합니다.

메시지 보내기

POST /messages

하나의 원자적 요청으로 영구 세션을 생성하고 첫 메시지를 보냅니다. 저장 없이 스트리밍만 수행하는 단발성 요청을 원한다면 ephemeral: true를 설정합니다. 이 경우 세션이나 메시지 기록이 저장되지 않고, 세션 ID도 반환되지 않으며, 이어서 계속할 수 없습니다.

요청 본문

예시 - 스트리밍(기본값)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

응답은 SSE 스트림입니다(이벤트 형식은 스트리밍 (SSE) 참조). 영구 요청에는 새로운 session_id가 포함되며, ephemeral: true 요청에는 session_id가 포함되지 않고 반드시 스트리밍을 사용해야 합니다.

예시 - JSON(비스트리밍)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

응답

스트리밍 응답은 스트리밍 (SSE)에 문서화된 SSE 이벤트를 발생시킵니다. 비스트리밍 응답은 세션 계속하기에 표시된 JSON 메시지 형태를 반환하며, 완료된 요청에 대한 stop_reason과 usage를 포함합니다.

비스트리밍 실행이 90초가 지나도 여전히 처리 중인 경우, API는 status: "processing", session_id, run_id, message와 함께 202 Accepted를 반환합니다. 실행은 응답이 반환되거나 클라이언트 연결이 끊긴 후에도 계속되므로, 세션의 메시지를 확인하거나 더 긴 워크플로에는 스트리밍을 사용하십시오.

오류

세션 계속하기

POST /sessions/{session_id}/messages

기존 영속 세션에 메시지를 전송하고 에이전트의 응답을 받습니다. 응답은 기본적으로 SSE를 통해 스트리밍되며, JSON으로 받으려면 stream: false로 설정하세요.

요청 본문

예시 - 스트리밍(기본값)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

예시 - JSON(비스트리밍)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

응답 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

세션에 이미 활성 실행이 있거나 대기 중인 메시지가 있는 경우, API는 status: "queued", session_id, run_id, message_id와 함께 JSON 202 Accepted를 반환합니다. 사용자 메시지는 해당 활성 실행에 의해 처리됩니다.

오류

멱등성

POST /messages와 POST /sessions/{session_id}/messages는 선택적으로 Idempotency-Key 헤더를 허용합니다. 네트워크 재시도나 중복 제출로 인해 중복된 실행이 생성되지 않도록, 논리적인 사용자 전송마다 고유한 키를 사용하십시오.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

비스트리밍: 재시도하면 Idempotent-Replayed: true 헤더와 함께 저장된 200 또는 202 응답이 반환됩니다.

스트리밍: 스트림은 재생되지 않습니다. 실행 중이거나 완료된 후에 재시도하면 원본 run_id와, 영속적인 요청의 경우 session_id가 포함된 멱등성 오류가 반환됩니다. 활성 실행을 확인하려면 GET /sessions/{session_id}/runs/{run_id}를 사용하고, 저장된 결과를 가져오려면 GET /sessions/{session_id}/messages를 사용하십시오.

완료된 스트리밍 재시도 예시:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

멱등성 오류

메시지 목록 조회

GET /sessions/{session_id}/messages

표시 가능한 대화 메시지의 페이지네이션된 목록을 반환합니다. 첫 번째 페이지에는 가장 최근 메시지가 포함되며, 각 페이지 내에서 메시지는 시간순(오래된 것부터)으로 정렬됩니다. sequence는 세션 내에서 안정적인 정렬 번호입니다.

쿼리 파라미터

예시

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

응답 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "files": []
    }
  ],
  "next_cursor": "",
  "has_more": false
}

메시지 객체

파일 객체

오류

메시지 조회

GET /sessions/{session_id}/messages/{message_id}

ID로 표시 가능한 단일 메시지를 조회합니다.

응답 200 OK

목록 응답과 동일한 구조의 단일 메시지 객체를 반환합니다.

오류

파일 첨부

file_urls 필드에 공개적으로 접근 가능한 HTTPS URL을 전달하십시오.

지원 형식

• 이미지: JPG, JPEG, PNG, WebP
• 문서: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• 코드: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

메시지를 조회할 때 첨부된 파일은 메시지의 files 배열에 나타납니다.

세션 API

세션은 최종 사용자와 에이전트 간의 지속적인 대화입니다. 대부분의 통합에서는 POST /messages를 사용하여 암묵적으로 세션을 생성할 수 있습니다.

세션 생성

POST /sessions

특정 에이전트에 연결된 비어 있는 영구 세션을 생성합니다. 첫 번째 메시지 이전에 세션 ID가 필요한 경우 사용합니다. 그렇지 않은 경우에는 POST /messages를 사용하는 것이 좋습니다.

참고: POST /sessions에서는 ephemeral을 사용할 수 없습니다. 저장이 필요 없는 단발성 요청에는 ephemeral: true와 함께 POST /messages를 사용하세요.

요청 본문

예시

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

응답 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

오류

세션 목록 조회

GET /sessions

귀하의 세션 목록을 최근 업데이트순으로 페이지네이션하여 반환합니다.

쿼리 파라미터

예시

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

응답 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAxIn0",
  "has_more": true
}

오류

세션 조회

GET /sessions/{session_id}

ID로 단일 세션을 조회합니다.

응답 200 OK

생성 응답과 동일한 구조의 세션 객체를 반환합니다.

오류

세션 이름 변경

PATCH /sessions/{session_id}

세션의 표시 이름을 업데이트합니다.

요청 본문

응답 200 OK

업데이트된 세션 객체를 반환합니다.

오류

세션 삭제

DELETE /sessions/{session_id}

세션과 해당 세션의 모든 메시지를 영구적으로 삭제합니다. 세션에 활성 실행이 없어야 합니다.

응답 204 No Content

오류

작업

이 엔드포인트들은 영속 세션에 대한 복구 및 편집 제어 기능입니다. 대부분의 통합은 취소(Cancel)만 필요하며, 세션 상태를 의도적으로 변경하거나 복구하고자 할 때만 다른 작업을 사용하십시오. 모든 작업은 최종 사용자에서 설명된 선택적 user 소유권 보호 기능을 지원합니다.

활성 실행 취소

POST /sessions/{session_id}/cancel

현재 진행 중인 에이전트 실행을 취소합니다. 취소 이전에 이미 완료된 메시지는 삭제되지 않습니다.

요청 본문

응답 204 No Content

오류

활성 실행 되돌리기

POST /sessions/{session_id}/undo

활성 실행을 취소하고 중지될 때까지 대기한 후, 해당 실행이 이미 추가한 메시지를 제거합니다. 되돌리기가 실행된 이후에는 추가 출력이 저장되지 않습니다.

요청 본문

응답 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

메시지가 완료되기 전에 실행이 취소된 경우, deleted는 빈 배열이 됩니다.

오류

최근 메시지 삭제

POST /sessions/{session_id}/messages/delete

유휴 상태인 세션에서 가장 최근 N개의 메시지를 삭제합니다. 세션에 활성 실행이 없어야 합니다.

요청 본문

응답 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

오류

세션 포크

POST /sessions/{session_id}/fork

원본 세션을 특정 메시지까지 복사하여 새 세션을 생성합니다. 원본 세션에는 활성 실행이 없어야 합니다.

요청 본문

응답 201 Created

세션 생성과 동일한 구조로 새로 생성된 세션 객체를 반환합니다.

오류

실행 상태 조회

GET /sessions/{session_id}/runs/{run_id}

활성 실행의 현재 상태를 반환합니다. SSE 연결이 끊어진 후 또는 run_id를 반환한 멱등성 응답 이후에 사용하십시오. 실행이 완료된 후에는 GET /sessions/{session_id}/messages로 결과를 조회하십시오.

응답 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

실행이 활성 상태인 동안 응답에는 최근 진행 상황에 대한 힌트가 포함될 수도 있습니다.

오류

크레딧

잔액 조회

GET /credits/balance

귀하의 현재 크레딧 잔액을 반환합니다.

응답 200 OK

{
  "balance": "123.45"
}

에이전트 API

대시보드에서 커스텀 에이전트를 생성하고 편집하십시오. 에이전트 생성 및 편집을 위한 API 지원은 곧 제공될 예정입니다.

예약/백그라운드 워크플로는 현재 API를 통해 지원되지 않습니다. 지원은 곧 제공될 예정입니다.

에이전트 목록 조회

GET /agents

귀하의 API 키에서 사용할 수 있는 에이전트를 반환합니다. 세션을 생성하거나 메시지를 보낼 때 agent 값을 사용하세요.

응답 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

모델

모델 목록 조회

GET /models

메시지를 보낼 때 model 필드에서 사용할 수 있는 모든 모델을 반환합니다.

응답 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "kimi-k2.6",
      "name": "Kimi K2.6",
      "thinking_variant": "kimi-k2.6-thinking"
    }
  ]
}

thinking_variant가 있는 모델은 확장 추론을 지원합니다. 이를 활성화하려면 model 필드에 변형 ID를 직접 사용하세요.

메시지를 보낼 때 model을 지정하지 않으면 에이전트의 기본값 모델이 사용됩니다.

문서

GET /docs?lang=en
GET /doc?lang=en

이 참조 문서를 Markdown 형식으로 반환합니다. 언어를 선택하려면 lang을 사용하세요.

스트리밍 (SSE)

stream이 생략되거나 true(기본값)인 경우, 메시지 응답은 Server-Sent Events로 전달됩니다. 가져오거나 렌더링할 준비가 된 메시지를 식별하려면 message_completed 이벤트를 사용하세요.

타임아웃: SSE 연결은 최대 60분까지 유지됩니다. 비스트리밍 요청은 최대 90초까지 대기한 후, 실행이 계속되는 동안 202 Accepted를 반환합니다.

연결 헤더

SSE 응답은 다음 헤더를 설정합니다:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id는 첫 SSE 이벤트 이전에 사용할 수 있습니다.

재연결 및 복구

SSE 스트림은 재생되지 않습니다. 연결이 끊어진 경우, 캡처해 둔 session_id와 run_id를 사용하여 상태를 복구하세요:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

실행이 아직 활성 상태라면, 현재 상태, 부분 텍스트, 최근 진행 상황이 반환됩니다. 404 not_found가 반환되면 해당 실행은 더 이상 활성 상태가 아니므로, 세션의 메시지를 가져와 완료된 출력을 대조하세요:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

프레임 형식

각 SSE 프레임은 다음과 같은 표준 형식을 따릅니다:

event: <event_type>
data: <json_payload>

두 개의 줄바꿈이 각 프레임을 종료합니다.

이벤트 유형

스트림에는 수명 주기, 텍스트 델타, 사고, 진행 상황, 경고, 메시지 완료, MCP 연결, 오류, 최종 및 ping 이벤트가 포함됩니다. 일부 이벤트 유형은 관련이 있을 때만 전송됩니다.

일시적(ephemeral) 요청(ephemeral: true)의 경우, 모든 SSE 이벤트에서 session_id가 생략됩니다. 해당 단일 스트림 내에서 이벤트를 연관시키려면 run_id만 사용하십시오.

영구(persistent) 요청에 대한 최종 조정을 위해서는 stream_ended를 기다린 다음 List Messages를 호출하십시오.

실행 범위 이벤트에 공통되는 필드:

stream_started

실행이 시작될 때 한 번 전송됩니다.

stream_delta

에이전트가 표시되는 응답 텍스트를 생성하는 동안 반복적으로 전송됩니다. seq 순서대로 chunk_content 값을 연결하여 스트리밍된 응답을 구성하십시오.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

에이전트가 사고(thinking) 출력을 내보내는 동안 반복적으로 전송됩니다. 별도의 사고 표시기나 추적 뷰에 사용하십시오. 최종 응답 텍스트에 연결하지 마십시오.

stream_progress

문서 읽기, 웹 검색 또는 사용자 작업 대기와 같이 생성 중 사용자에게 표시되는 활동을 보고합니다. 이러한 이벤트는 임시 UI 표시용입니다. 알 수 없는 필드는 무시하세요. 권위 있는 메시지 기록에는 완료된 메시지를 사용하세요.

고급: 메시지 요청은 stream_progress만 생략하기 위해 include_progress: false를 받아들입니다. 라이프사이클 이벤트, ping, message_completed, 오류 및 종료 이벤트는 관련이 있을 경우 여전히 전송됩니다.

일부 진행 상황 이벤트에는 선택적 표시 힌트로 url, file_name, 또는 server_name이 포함될 수 있습니다.

message_completed

메시지가 완료되어 가져오거나 렌더링할 준비가 될 때마다 전송됩니다.

이것은 경계 마커일 뿐, 전체 메시지 객체가 아닙니다. 콘텐츠나 메타데이터가 필요한 경우 메시지를 가져오십시오.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"Jenova"},"type":"external"}

mcp_connection

에이전트가 계속하기 전에 최종 사용자가 하나 이상의 MCP 서버를 연결하거나 승인해야 할 때 전송됩니다. 이 이벤트는 스트리밍 모드에서만 사용할 수 있습니다.

mcp_connection_resolved

MCP 연결 사용자 작업이 해결되었거나 만료되었을 때 전송됩니다.

공통 실행 범위 필드 외에 추가 필드는 없습니다.

warning

실행 중 치명적이지 않은 경고에 대해 전송됩니다.

stream_error

실행이 실패했을 때 전송됩니다. 이어서 success:false 및 stop_reason:"error"가 포함된 최종 stream_ended 이벤트가 뒤따를 수 있습니다.

stream_ended

실행이 종료되면 한 번 전송됩니다. 이는 스트림의 마지막 이벤트입니다.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

실패 예시:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

프록시/CDN 타임아웃을 방지하기 위해 15초마다 전송되는 킵얼라이브 프레임입니다. 클라이언트에서는 무시하십시오.

MCP 서버 통합

**Model Context Protocol (MCP)**을 통해 귀하의 에이전트를 외부 도구에 연결하십시오:

• Jenova 관리형 MCP 서버: 검색, 콘텐츠 검색, 문서 생성 및 기타 기본 제공 기능을 위해 Jenova가 호스팅하는 서버
• 원격 MCP 서버: 귀하의 에이전트를 위해 구성된 기타 원격 MCP 서버

MCP 서버는 에이전트를 생성하거나 편집할 때 대시보드에서 구성해야 합니다. 자체 MCP 서버를 사용하려면 이를 커스텀 에이전트에 추가한 다음 API를 통해 해당 에이전트를 호출하십시오. API는 에이전트 구성에서 활성화된 도구를 실행하며, API 요청에서 추가 설정이 필요하지 않습니다.

에이전트가 응답 중 MCP 도구를 사용할 때, 진행 이벤트는 발생하는 대로 스트림으로 전송됩니다:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

실행 중 에이전트가 최종 사용자에게 MCP 서버 연결 또는 승인을 요구하는 경우, 스트리밍 응답에 mcp_connection 및 mcp_connection_resolved 이벤트가 포함될 수 있습니다. 최종 사용자에게 연결 서버 목록을 표시하고, 제공된 auth_url이 있으면 여세요. 사용자가 서버를 연결하거나 승인하는 동안 SSE 스트림을 열어 두세요.

승인이 완료되면 Jenova가 토큰을 저장하고, 승인 창에는 완료 페이지가 표시되며, 동일한 실행이 자동으로 계속됩니다. 최종 사용자는 메시지를 다시 보낼 필요가 없습니다.

최종 사용자가 user_action_deadline_unix 전에 연결, 승인, 건너뛰기 또는 음소거를 하지 않으면 실행은 stop_reason:"user_action_timeout"으로 종료됩니다. POST /sessions/{session_id}/cancel로 활성 실행을 취소할 수도 있습니다.

auth_url을 클라이언트 측에 저장하세요. 승인 중 클라이언트 연결이 끊어져도 이 URL은 user_action_deadline_unix까지 유효합니다. 지속 요청의 경우 Get Run Status로 다시 연결하거나 실행이 끝난 후 메시지를 가져오세요.

비스트리밍 요청(stream: false)은 MCP 연결 사용자 작업을 지원하지 않습니다. 이 상호작용이 필요할 수 있는 에이전트에는 스트리밍을 사용하세요.

MCP 연결 건너뛰기

POST /sessions/{session_id}/mcp/connection/skip

대기 중인 MCP 연결 사용자 작업을 무시하고 해당 연결 없이 실행을 계속하도록 합니다.

동일한 API 사용자에 대해 한 서버의 향후 연결 프롬프트를 음소거하려면 mcp_server_id와 mute를 포함하세요. 지원되는 값은 24h 및 forever입니다.

요청 본문

응답 204 No Content

스트림은 mcp_connection_resolved를 내보낸 다음, 실행은 동일한 run_id로 계속됩니다.

오류

결제

모든 비용은 귀하의 개발자 크레딧 잔액에서 차감됩니다. www.jenova.ai/platform에서 사용량을 확인하고 크레딧을 충전할 수 있습니다.

가격

메시지 비용은 다음에 따라 결정됩니다:

• 모델 - 모델마다 토큰당 비용이 다릅니다
• 컨텍스트 길이 - 세션이 길어질수록 요청당 더 많은 입력 토큰을 소비합니다
• 워크플로 복잡도 - 워크플로가 길어지고 도구 사용(웹 검색, 파일 생성, 문서 분석)이 늘어나면 전체 토큰 소비량이 증가합니다

실제 비용은 스트리밍 요청의 경우 stream_ended.usage.cost로, 비스트리밍 JSON 요청의 경우 usage.cost로 반환됩니다.

크레딧 보류

각 새 메시지 실행은 실행이 시작되기 전에 귀하의 크레딧 잔액에 $0.50 보류를 설정합니다. 이는 실행을 위한 자금을 예약하는 것입니다. 활성 실행 중 대기 중인 후속 메시지는 추가 보류를 생성하지 않으며, 활성 실행의 사용량은 귀하의 남은 잔액과 대조하여 확인됩니다.

실행이 완료되면 보류는 실제 비용으로 정산되며 차액은 해제됩니다. 취소되거나 실패한 실행은 이미 발생한 사용량에 대해서만 청구됩니다. 요청이 모델에 도달하기 전에 실패하면 전체 보류가 해제됩니다.

이는 진행 중인 요청 동안 귀하의 사용 가능한 잔액이 일시적으로 낮게 표시될 수 있음을 의미합니다. 기존 세션에 메시지를 보내거나 임시 메시지를 보내려면 최소 $0.50의 사용 가능한 잔액이 필요합니다. 최초의 지속 세션 POST /messages 요청은 세션을 생성하며, 메시지 보류 금액과 세션 생성 요금을 충당하기 위해 최소 $0.51이 필요합니다.

속도 제한

모든 개발자 계정은 세 가지 속도 제한 차원의 적용을 받습니다:

GET 및 HEAD 요청은 동시 슬롯을 소비하지 않습니다. cancel, undo, mcp/connection/skip도 동시 슬롯을 소비하지 않으므로 모든 슬롯이 사용 중이어도 이러한 작업은 계속 사용할 수 있습니다. 이러한 요청은 여전히 RPM 및 RPD에 계산됩니다.

응답 헤더

인증된 API 응답에는 속도 제한 헤더가 포함됩니다:

제한을 초과하면 API는 429 Too Many Requests를 반환합니다:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}

오류 처리

즉시 발생하는 HTTP 오류와 스트리밍이 아닌 실행 오류는 일관된 형식을 따릅니다:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

오류 메시지는 lang 파라미터를 기준으로 현지화됩니다(현지화 참고).

스트리밍 실행 오류는 stream_error 이벤트로 전달됩니다. 실패한 실행이라도 success:false와 stop_reason이 설정된 최종 stream_ended 이벤트가 전송될 수 있습니다. 스트리밍이 아닌 실행 오류에는 비용 데이터를 사용할 수 있는 경우 최상위 usage 객체가 포함될 수도 있습니다.

엔드포인트별 오류는 각 엔드포인트 하위에 인라인으로 문서화되어 있습니다.

시작 후 실행 오류

실행 오류는 메시지 실행이 이미 시작된 후에 나타납니다. 스트리밍 모드에서는 stream_error 이벤트로 나타나며, 이후 success:false가 설정된 stream_ended가 이어질 수 있습니다. 스트리밍이 아닌 모드에서는 아래 HTTP 상태와 함께 JSON 오류 응답으로 반환됩니다.

페이지네이션

목록 엔드포인트는 커서 기반 페이지네이션을 사용합니다:

{
  "items": [],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAyIn0",
  "has_more": true
}

다음 페이지를 가져오려면 next_cursor를 cursor 쿼리 파라미터로 전달하십시오. has_more가 false이면 더 이상 결과가 없습니다.

현지화

모든 엔드포인트는 오류 메시지 및 현지화된 콘텐츠의 언어를 제어하기 위해 선택적 lang 쿼리 파라미터를 허용합니다.

모든 요청 URL에 ?lang=xx를 추가할 수 있습니다:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

지원 언어: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

개인정보 보호 및 데이터

Jenova는 Jenova 모델을 훈련시키기 위해 API 프롬프트, 출력, 대화 기록, 업로드된 파일, 에이전트 지시사항 또는 지식 베이스를 사용하지 않습니다.

Jenova는 제3자 모델 제공업체와 관련하여, 고객 콘텐츠가 제공업체 모델 훈련에 사용되지 않도록 하기 위해 상업용 API 채널, 계정 설정, 계약상 약속 또는 옵트아웃을 활용합니다.

Jenova는 미국 인프라를 사용하여 API 데이터를 저장하고 처리합니다. 제3자 제공업체는 개인정보 보호정책 및 이용약관에 설명된 대로 다른 관할권에서 데이터를 처리할 수 있습니다.

전체 내용은 이용약관, 개인정보 보호정책, 사용 정책을 참조하십시오.

지원

• 대시보드: www.jenova.ai/platform
• 이메일: [email protected]