Pokee Enterprise API: 영구 샌드박스 에이전트, 가격 및 첫 API 호출

Pokee Enterprise API는 각 고객을 위해 전용적이고 지속적인 샌드박스 내에서 장문 AI 에이전트를 실행하는 REST API입니다. 사용자는 세션을 생성하고 메시지를 전송하며, 서버 전송 이벤트(SSE) 스트림으로 에이전트의 응답을 읽을 수 있습니다. 세션은 파일, 사용자 정의 기술(custom skills), 사용자의 도구 및 세션 간에 유지되는 메모리를 보유할 수 있습니다. 접근 권한은 Pokee 데모 요청을 통해 이루어지며, 셀프 서비스 가입은 지원하지 않습니다. 아래에서는 세션 및 스트림 작동 방식, 첫 번째 호출, Pokee Isaac 가격, 제한 사항 및 코딩 에이전트로 Apidog CLI를 사용하여 엔드포인트를 테스트하는 방법에 대해 자세히 설명합니다. 모든 수치는 2026년 10월 28일에 작성된 Pokee 문서에서 가져온 것입니다.

Pokee Enterprise API란 무엇인가?

Pokee Enterprise API (Pokee는 Enterprise Responses API라고 부름)를 사용하면 분이 아닌 수 분이 걸리는 에이전트 기반 워크플로우를 실행할 수 있습니다. 각 테넌트는 프라이빗 워크스페이스, 안정적인 베어러 토큰 및 자체 서브도메인(https://your-tenant.enterprise.pokee.ai)을 갖게 됩니다. 해당 워크스페이스 내에서 각 세션은 자체 샌드박스 내의 하나의 에이전트 프로세스로 작동합니다.

일반적인 채팅 호출은 하나의 프롬프트를 응답하고 그 이후를 잊습니다. 하지만 Pokee 세션은 대화 내용, 파일 및 작업 상태를 유지하므로 에이전트가 여러 턴에 걸쳐 연구하고 파일을 작성하며 도구를 호출할 수 있습니다. 만약 Claude Managed Agents에 관한 저희 가이드를 읽으셨다면, 이 구조가 익숙할 것입니다. 제공자가 에이전트 루프와 샌드박스를 호스팅하고 사용자가 HTTP를 통해 제어하는 방식입니다.

이 기능은 테넌트 격리 및 엔터프라이즈 네트워크 제어(IP 허용 목록, mTLS, AWS PrivateLink, 리전 고정)를 갖춘 호스팅 에이전트를 원하는 팀을 위해 설계되었으며, Pokee는 요청 시 사용 가능한 사항으로 명시하고 있습니다.

핵심 개념: 세션, 파일, 기술 및 메모리

이 API는 네 가지 빌딩 블록으로 구성되어 있습니다.

컨셉	엔드포인트	제공 내용
세션(Sessions)	`POST /v1/sessions`	세션별 하나의 에이전트 프로세스, 자체 히스토리, 파일 범위 및 모델
파일(Files)	`/v1/sessions/{id}/files/{path}`	워크스페이스 파일 업로드, 다운로드, 목록 조회 및 삭제 (업로드당 약 100MB)
기술(Skills)	`POST /v1/skills/{name}`	루트에 `SKILL.md`가 있는 zip 번들을 설치합니다. 새 세션에 적용됨
메모리(Memory)	`.pokee/*.md`, `.memory/MEMORY.md`	시스템 프롬프트에 추가된 테넌트 지침 및 세션 간 메모리

몇 가지 세션 상세 사항이 중요합니다:

지속성(Persistence). 기본적으로 persistent는 false이며, 마지막 응답 후 5분 뒤에 세션이 스스로 파괴됩니다. true로 설정하면 세션의 ttl(기본 14,400초, 즉 4시간)이 만료되거나 사용자가 삭제할 때까지 세션을 유지할 수 있습니다.
모델 잠금(Model lock). 생성 시 전달하는 model은 해당 세션의 모든 턴에 적용됩니다.
파일 범위(File scope). file_access에 read 및 write 경로 목록을 전달하여 에이전트가 접근할 수 있는 범위를 제한할 수 있으며, HTTP 파일 API는 이 범위 밖의 요청에 대해 403을 반환합니다.
한 번에 한 턴(One turn at a time). 한 턴이 진행 중일 때 두 번째 메시지를 보내면 409 Conflict가 반환됩니다.

첫 번째 Pokee API 호출 방법

Pokee는 두 가지 값을 외적(out of band)으로 제공합니다. 바로 테넌트 URL과 pk_<tenant>_<token> 형태의 키입니다. 그런 다음 첫 번째 호출은 세 단계를 거칩니다.

게이트웨이가 활성화되어 있는지 확인합니다 (인증 불필요).
세션을 생성하고 해당 id를 유지합니다.
메시지를 포스트하고 SSE 스트림을 읽습니다.

export POKEE_API="https://your-tenant.enterprise.pokee.ai"
export POKEE_KEY="pk_<tenant>_<token>"

curl "$POKEE_API/health"

SID=$(curl -s -X POST "$POKEE_API/v1/sessions" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persistent": true}' | jq -r '.id')

curl -N -i -X POST "$POKEE_API/v1/sessions/$SID/messages" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the files in my workspace in three bullets."}'

-i 플래그를 사용하면 헤더를 출력합니다. X-Response-Id(msg_와 24개의 16진수 문자)를 저장해 두세요. 이는 턴을 재개하거나 취소할 때 필요합니다.

각 이벤트는 세 줄로 구성됩니다: id:, event:, data:. message.created를 볼 수 있고, text.delta 청크(그리고 thinking.* 또는 tool_use.* 이벤트)가 표시된 다음, message.completed, message.cancelled 또는 message.error로 스트림이 종료됩니다. 만약 SSE가 낯설다면, MDN의 서버 전송 이벤트 가이드가 형식을 설명하며, SSE를 통해 스트리밍되는 LLM API 테스트에 관한 저희 게시물은 청크를 읽는 방법을 보여줍니다.

Pokee Enterprise API 세션 흐름: 세션 생성, 메시지 포스팅, SSE 스트림 읽기, 재개 및 취소 분기

도구 호출: 두 가지 표면

Pokee는 에이전트가 함수를 호출할 수 있는 두 가지 방법을 제공하며, 두 방법 모두 OpenAI 스타일의 함수 정의를 사용합니다.

	상태 비저장형 `/v1/responses`	세션 도구(Session tools)
에이전트 루프	없음, 한 번의 추론 왕복	기술 및 파일을 포함한 완전한 에이전트 세션
상태(State)	각 호출마다 전체 히스토리를 전송	서버가 대화를 유지함
호출 모양	`output[]` 내의 `function_call` 항목	스트림 중간에 나타나는 `tool_call.requested` SSE 이벤트
계속하는 방법	`function_call_output` 항목이 있는 새로운 호출	`POST /v1/sessions/{id}/tool_results`

상태 비저장형 경로는 OpenAI Responses API를 위해 작성된 코드 뒤에 Pokee를 통합할 때 선택해야 할 방식입니다. 이는 와이어 형태가 일치하기 때문입니다. 이 방식은 요청당 최대 128개의 도구, 도구 이름 최대 64자, 설명 최대 16KiB를 허용합니다. 또한 reasoning.effort(minimal은 기본값으로, 확장된 사고를 비활성화합니다; low, medium 및 high로 설정하면 활성화됩니다)을 받아 생각의 노력을 조절할 수 있습니다. 출력 기본값은 4,096 토큰이며 최대 32,000 토큰으로 제한됩니다.

세션 도구는 에이전트가 한 턴에 추론하고, 기술을 실행하며, 때로는 사용자 시스템을 호출해야 할 때 적합합니다. 이는 세션 생성 시 등록할 수 있습니다.

Pokee 도구 호출 비교: stateless /v1/responses 대 SSE를 사용한 세션 모드 도구

재개, 취소 및 멱등성 키

긴 턴은 짧은 호출과는 다른 방식으로 실패할 수 있습니다. Pokee는 2026년 5월 4일에 변경 로그를 통해 세 가지 수정 사항을 추가했습니다.

재개(Resume). 클라이언트가 스트림 중간에 끊어져도 에이전트는 계속 실행됩니다. Last-Event-ID 헤더와 함께 GET /v1/sessions/{id}/responses/{rid}/events로 다시 연결하면 서버가 다음 이벤트부터 다시 전송합니다. 닫힌 턴은 120초 동안 사용할 수 있으며, 재개한다고 해서 토큰이 재청구되지는 않습니다.
취소(Cancel). POST /v1/sessions/{id}/responses/{rid}/cancel 호출은 202를 반환하고 스트림은 message.cancelled로 종료됩니다. 취소된 턴의 부분적인 사용량은 청구되지 않습니다. 세션과 파일은 계속 살아있습니다.
멱등성 키(Idempotency keys). 메시지 POST 시 Idempotency-Key: <uuid>를 전송하세요. 동일한 키와 본문으로 재시도하면 두 번째 턴을 시작하는 대신 원래의 응답 ID를 반환합니다. 키는 24시간 동안 유지되며, 다른 본문을 가진 동일한 키는 422를 반환합니다.

상태 비저장형 /v1/responses 경로는 stream이 true일 때 이 세 가지 모두를 지원합니다.

Pokee Isaac 모델 및 가격

Pokee는 모델 및 가격 페이지에서 두 개의 Isaac 계층을 공개하고 있습니다. 가격은 1백만 토큰당 책정됩니다.

모델	입력	출력	캐시 읽기
`pokee-isaac-high-reasoning`	$3	$15	$0.30
`pokee-isaac`	$0.30	$5	$0.10

새 테넌트는 model을 생략할 경우 기본적으로 pokee-isaac-high-reasoning 모델을 사용합니다. Kimi, GPT-5.5 및 Gemini 백엔드는 계약에 따라 테넌트별로 제공됩니다. 문서에는 무료 티어나 최소 계약 조건이 명시되어 있지 않으므로, 해당 조건은 Pokee에 문의하십시오.

또한 2026년 8월 7일에 추가된 Direct Isaac API가 있습니다. 이는 에이전트 루프나 도구가 없는 OpenAI와 호환되는 POST /v1/chat/completions 경로입니다. 테넌트별로 활성화되며 pokee-isaac만 수용합니다. 대용량 요청(20만 토큰 및 200만 토큰 이상)은 자동으로 더 큰 컨텍스트 풀로 라우팅됩니다. GET /v1/usage를 통해 크레딧 잔액을 확인할 수 있습니다.

문서에서 주의할 점이 있습니다: 테넌트 베어러 토큰은 직접적인 API 키입니다. 서버나 자체 프록시 뒤에 보관하고, 브라우저, 모바일 또는 데스크톱 코드에는 절대 두지 마십시오.

제한 사항 및 오류 코드

이것은 제한 사항 및 오류 페이지의 기본값입니다. Pokee는 요청 시 이들 중 하나를 발생시킬 수 있다고 명시합니다.

제한 항목	기본값
동시 세션 수	10
턴 타임아웃	90분
세션 TTL	4시간
시간/일당 턴 수	300 / 5,000
시간/일당 토큰 수	20M / 200M
최대 업로드 용량	호출당 약 100MB
최대 워크스페이스 크기	100 GB

대부분 처리하게 될 오류 코드는 401 (잘못되었거나 누락된 키), 402 (크레딧 부족, 하드 크레딧 모드 전용), 403 (세션 범위 밖 경로), 409 (세션 바쁨), 422 (다른 본문으로 멱등성 키 재사용), 429 (사용량 제한), 그리고 500 (백오프를 이용한 재시도)입니다. 오류는 {"error": "<이름>", "message": "<세부 내용>"} 형식으로 반환됩니다.

Apidog CLI로 Pokee API를 테스트하기

세션 API에는 명시해야 할 많은 계약 사항이 있습니다: 생성 시 201, sess_ ID, 바쁠 때 409, 삭제 시 204, 취소 시 202. 코딩 에이전트는 사용자가 작업하는 동안 이러한 검사를 작성하고 실행할 수 있습니다. Apidog CLI는 Claude Code, Codex 또는 Cursor에게 이 작업을 수행할 명령을 제공합니다.

단 한 번만 설정하세요:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

그런 다음 에이전트에게 한 번의 프롬프트를 제공하세요:

Pokee Enterprise API 엔드포인트 /health, POST/GET/DELETE /v1/sessions, /v1/sessions/{id}/responses/{rid}/cancel 및 /v1/usage에 대한 OpenAPI 파일을 작성하고, 이를 Apidog 프로젝트 <projectId>에 임포트하고, 제 테넌트 URL용 환경을 생성한 다음, 생성 시 201과 "sess_"로 시작하는 id가 있는지, 삭제 시 204가 나오는지, /v1/usage에서 크레딧 잔액이 있는지 확인하는 테스트 케이스를 추가하세요. 실행하고 실패를 요약해 주세요. POKEE_KEY는 파일이 아닌 쉘에서 읽어오세요.

에이전트는 명세를 임포트하고, 각 페이로드를 CLI의 스키마와 대조한 다음, 케이스를 생성하고 실행합니다:

apidog import --project <projectId> --format openapi --file ./pokee-openapi.json
apidog environment create pokee-tenant --project <projectId> --base-url https://your-tenant.enterprise.pokee.ai
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file create-session.json
apidog test-case create --project <projectId> --file create-session.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "POKEE_KEY=$POKEE_KEY" -r cli,junit

--env-var를 사용하면 키가 에이전트가 작성하는 어떤 파일에도 포함되지 않습니다. 이 케이스들은 JSON 엔드포인트를 다룹니다. SSE 스트림 자체는 Apidog 앱에서 더 쉽게 확인되는데, 스트리밍된 이벤트를 렌더링하기 때문입니다 (Apidog에서 SSE 테스트 보기 참조). 동일한 apidog run 명령어를 -r junit과 함께 사용하면 CI에 통합할 수 있으며, 저희 Apidog CLI CI/CD 가이드가 이를 보여줍니다. 에이전트 내에서 CLI를 처음 사용하는 경우 Apidog CLI in Claude Code부터 시작하세요. Apidog의 무료 플랜은 최대 4명의 사용자를 지원합니다.

Sharkly의 역할

Pokee 에이전트 또는 코딩 에이전트가 90분이 걸리는 작업을 실행한다면, 누가 무엇을 해야 할지 결정하고 결과를 확인하는 누군가가 필요합니다. 로그 파일에 있는 세션 ID는 작업 대기열이 아닙니다. Sharkly는 AI 에이전트와 사람이 작업을 공유하는 태스크 보드입니다. 에이전트나 팀원에게 작업을 할당하고 상태를 추적하며 배포 전에 출력을 검토할 수 있습니다. 무료로 시작할 수 있으므로, 하나의 긴 에이전트 작업을 보드에 올려 검토 방식이 팀에 맞는지 확인한 후 확장할 수 있습니다.

자주 묻는 질문(FAQ)

Pokee Enterprise API의 무료 플랜이 있나요? 문서에는 나와 있지 않습니다. 액세스는 데모 요청으로 시작되며, Pokee가 테넌트 URL과 키를 외적 방식(out of band)으로 프로비저닝해 드립니다. 가격은 위의 Isaac 티어 기준으로 토큰당 부과됩니다.

Pokee API가 OpenAI와 호환되나요? 부분적으로 그렇습니다. 상태 비저장형 /v1/responses 경로는 함수 호출에 대해 OpenAI의 응답 와이어 형식을 일치시키며, Direct Isaac 경로는 Chat Completions 요청 형식을 수용합니다. 세션 엔드포인트는 Pokee 고유의 방식입니다.

Pokee 에이전트의 턴 실행 시간은 얼마나 걸릴 수 있나요? 기본 턴 타임아웃은 90분이며 기본 세션 TTL은 4시간입니다. 둘 다 요청 시 늘릴 수 있습니다.

스트림 도중에 클라이언트가 연결이 끊어지면 어떻게 되나요? 에이전트는 계속 작동합니다. 턴 종료 후 120초 이내에 Last-Event-ID를 포함하여 재개 엔드포인트로 다시 연결하면 재청구 없이 나머지 이벤트를 받을 수 있습니다.

다른 호스팅 에이전트 API와 비교하면 어떤가요? 이는 OpenAI Agents API와 같은 호스팅 에이전트 솔루션과 유사합니다. 저희 OpenAI 에이전트 옵션 비교가 다음으로 읽어보시면 좋으며, AI 에이전트를 위한 CubeSandbox가 샌드박스 측면을 다루고 있습니다.