TL;DR
Kimi Hosted Agents는 지속 세션, 도구 실행, 클라우드 샌드박스를 통해 다단계 AI 작업을 실행합니다. 이 가이드는 Bash, curl, jq를 사용해 Kimi API 키에서 시작해 다운로드 가능한 3장짜리 프레젠테이션까지 만들어 가는 방법을 설명합니다. 먼저 자체 포함 프롬프트로 하나의 작업을 완성하세요. 이후 업로드한 문서를 추가하고, 비즈니스 도구를 연결하며, 실제 배포 애플리케이션에서 중요한 실패를 처리합니다.
Key Takeaways
- Kimi Hosted Agents는 에이전트 정의, 실행 환경, 세션을 연결합니다. 워크플로우 전반에서 이들의 ID를 계속 보관하세요.
- 작고 검증 가능한 결과부터 시작하세요. 첫 예시는 허구 데이터와 확인 가능한 계산을 포함한 프레젠테이션을 생성합니다.
- 이벤트 스트림으로 실행을 추적하고, 전달된 파일을 점검하세요. HTTP 성공 응답만으로 작업 성공을 보장하지 않습니다.
- 작동하는 예시를 파일 입력, 커스텀 도구, MCP 서비스로 확장하세요. 각 통합은 고유한 실행 및 자격 증명 요구 사항이 있습니다.
- 추론, 샌드박스 런타임, 플러그인 사용 비용을 모두 예산에 반영하세요. 수용 가능한 결과를 얻기 위해 필요한 재실행도 포함합니다.
What Is Kimi Hosted Agents?
Moonshot AI는 2026년 11월 5일에 Kimi Hosted Agents를 발표하며, 장기 실행 에이전트를 구축하는 엔터프라이즈와 개발자를 위한 서비스로 포지셔닝했습니다.
이 제품은 Harness as a Service 접근 방식을 사용합니다. 하니스(harness)는 상태 유지, 도구 호출, 실행 관리, 중단 복구 등 작업 진행 방식을 관리하는 모델 주변 소프트웨어입니다.
주간 리서치 워크플로우를 생각해 보세요. 텍스트 생성은 한 단계에 불과합니다. 애플리케이션은 출처를 가져오고, 파일을 처리하고, 차트를 만들고, 프레젠테이션을 저장하며, 연결이 끊긴 뒤에도 이어서 진행할 수 있을 만큼의 상태를 보존해야 할 수 있습니다.
Hosted Agents는 그 운영 레이어를 제공합니다. 팀은 여전히 비즈니스 작업을 정의하고, 통합을 선택하며, 수용 가능한 결과의 기준을 결정합니다.
Kimi의 공식 아키텍처는 호스티드 런타임이 사용하는 애플리케이션, 플랫폼 서비스, 실행 코어를 보여줍니다.
첫 통합을 위한 핵심 기능
- 지속 세션은 작업의 입력, 실행 이벤트, 출력을 함께 보존합니다.
- 클라우드 샌드박스는 파일을 처리하고 결과물을 만들기 위한 도구를 제공합니다.
- 스킬과 플러그인은 재사용 가능한 기능을 패키징하며, 커스텀 도구와 MCP 서비스는 자체 시스템을 연결합니다.
첫 체크포인트는 열어보고 점검할 수 있는 프레젠테이션입니다. 의존성을 추가하거나 기존 워크플로우를 샌드박스로 옮길 때 상세 런타임 사양이 유용해집니다. 사용 가능한 환경은 샌드박스 레퍼런스에 문서화되어 있습니다.
What Do You Need Before Calling the Kimi Hosted Agents API?
- Kimi 플랫폼 계정(Hosted Agents 접근 권한 포함)과 API 키
- macOS, Linux, 또는 WSL이 설치된 Windows에서 Bash, curl, jq
- 두 개의 터미널: 터미널 A는 요청 전송, 터미널 B는 실행 이벤트 모니터링
- 생성된 PPTX를 열 수 있는 프레젠테이션 뷰어
콘솔의 API 관리 영역에서 Kimi 플랫폼 계정과 API 키를 생성하세요. 설정과 작업 명령을 위해 터미널 A(하나의 Bash 터미널)를 사용합니다. 이후 단계에서 변수를 재사용할 수 있도록 이 터미널을 열어 둡니다. 계속하기 전에 curl과 jq를 설치하세요. 예시는 베타 API 버전 2026-09-01-beta를 사용합니다.
command -v curl &&
command -v jq &&
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
export KIMI_API_KEY &&
export KIMI_BASE="https://api.moonshot.cn/v1" &&
export KIMI_VERSION="2026-09-01-beta"
How Do You Run Your First Kimi Hosted Agents Task
워크플로우는 Kimi의 REST API 빠른 시작을 따릅니다. 공식 PPT 어시스턴트를 사용해 짧은 허구의 비즈니스 브리프를 프레젠테이션으로 변환합니다. 모든 입력 데이터는 요청에 포함되므로 첫 실행에는 파일 업로드나 사설 데이터 연결이 필요하지 않습니다.
각 블록을 순서대로 실행하고 다음으로 진행하기 전에 출력 결과를 확인하세요. &&로 이어진 명령은 요청이나 검증이 실패하면 해당 블록을 중단합니다. 다음 단계로 이동하기 전에 보고된 오류를 해결하세요. 기존 설정을 재시도할 때는 동일한 환경 및 세션 ID를 유지합니다.
Step 1: 공식 PPT 어시스턴트 선택
사용 가능한 에이전트를 가져와 이름과 정의를 확인합니다. 프롬프트가 표시되면 PPT 스킬이 구성된 공식 PPT 어시스턴트의 ID를 붙여넣으세요. 마지막 명령은 선택한 항목이 반환된 목록에 존재하는지 확인하고 해당 정의를 출력합니다.
curl --fail-with-body -sS "$KIMI_BASE/agents" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o agents.json &&
jq -r '.items[] | [.id, .name] | @tsv' agents.json &&
read -rp "PPT assistant ID: " AGENT_ID &&
jq -e --arg id "$AGENT_ID" \
'.items[] | select(.id == $id)' agents.json &&
export AGENT_ID
마지막 명령은 선택한 에이전트의 정의를 출력해야 합니다. 프로젝트에서 어시스턴트를 사용할 수 없다면, 계속하기 전에 공식 PPT 에이전트 구성으로 동등한 에이전트를 준비하세요.
Step 2: 클라우드 환경 생성
Environment는 설치 패키지, 네트워크 접근, 시작 명령 등 실행 설정의 재사용 가능한 구성입니다. 이를 재사용하면 이후 세션에서 동일한 설정을 사용할 수 있습니다. 각 클라우드 세션은 여전히 고유한 샌드박스와 워크스페이스를 받습니다. 구성 옵션은 환경 가이드에 나와 있습니다.
환경은 한 번 생성하고 ID를 보관하세요. 클라우드 이미지 빌드는 비동기로 진행되므로 빌드 상태가 ready가 될 때까지 세션을 만들지 마세요. API가 준비되지 않았다고 보고하면 대기 후 동일한 ENVIRONMENT_ID로 재시도하세요. 다른 환경을 만든다고 해서 첫 빌드가 완료되지는 않습니다.
curl --fail-with-body -sS "$KIMI_BASE/environments" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
-d '{"name":"First presentation environment","config":{"type":"cloud"}}' \
-o environment.json &&
ENVIRONMENT_ID="$(jq -er '.id | strings | select(length > 0)' environment.json)" &&
export ENVIRONMENT_ID &&
printf 'Environment: %s\n' "$ENVIRONMENT_ID"
Step 3: 세션 생성
세션은 생성 시점의 Agent 버전과 사용 가능한 Environment 버전을 고정합니다. 아래 요청은 두 ID를 제공하며, 플랫폼이 버전을 선택하고 고정합니다. 정확한 Agent 버전을 선택하려면 agent_version을 설정할 수도 있습니다. 이후 Agent나 Environment를 업데이트해도 기존 세션은 업데이트되지 않으며, 세션은 environment_id를 변경할 수 없습니다. 수정된 구성을 사용하려면 새 세션을 만드세요. 이 규칙은 세션 생성에 문서화되어 있습니다.
반환된 세션 ID를 이벤트 스트림과 작업 요청 모두에 사용하세요. 새 세션은 idle로 시작하며, user.message를 보내면 작업이 시작됩니다.
test -n "$AGENT_ID" &&
test -n "$ENVIRONMENT_ID" &&
jq -n --arg agent "$AGENT_ID" --arg env "$ENVIRONMENT_ID" \
'{agent_id:$agent,environment_id:$env,title:"First product update presentation"}' \
> session-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @session-request.json \
-o session.json &&
SESSION_ID="$(jq -er '.id | strings | select(length > 0)' session.json)" &&
export SESSION_ID &&
printf 'Session: %s\n' "$SESSION_ID"
Step 4: 두 번째 터미널에서 실행 모니터링
터미널 B를 엽니다. 동일한 API 키를 입력한 다음 터미널 A에서 출력된 세션 ID를 붙여넣습니다. 서버 전송 이벤트 스트림은 터미널 A가 작업을 제출하는 동안 실행 업데이트를 표시합니다. 결과를 점검할 때까지 이 터미널 연결을 유지하세요.
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
read -rp "Session ID from Terminal A: " SESSION_ID &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS -N \
"https://api.moonshot.cn/v1/sessions/$SESSION_ID/events/stream" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: 2026-09-01-beta" \
-H "Accept: text/event-stream"
Step 5: 자체 포함 작업 보내기
터미널 A로 돌아가 user.message 이벤트를 보냅니다. 예시는 허구 수치를 사용하며 구체적인 결과물을 요청합니다. 에이전트는 지원 비즈니스 데이터를 검색하지 말고 제공된 사실만 사용해야 합니다.
cat > task.json <<'JSON' &&
{
"events": [{
"type": "user.message",
"data": {"content": [{
"type": "text",
"text": "Create a three-slide PPTX for a fictional product called Northstar. Use only these supplied facts: the pilot has 120 users; 90 were active this week; the team plans to interview 10 users next week. Slide 1: pilot overview. Slide 2: weekly activity, including the active-user percentage. Slide 3: next steps. Label the business and data as fictional. Do not browse the web. Save the presentation and register the PPTX as a downloadable artifact using save_artifact."
}]}
}]
}
JSON
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @task.json
Step 6: 프레젠테이션 다운로드 및 점검
터미널 B에서 session.status 이벤트를 확인하세요. 세션이 idle로 돌아오면 중단 이유를 점검합니다. end_turn은 턴이 완료되었음을, requires_action은 클라이언트가 도구 결과를 제공하거나 확인을 처리해야 함을 의미합니다. session.error 이벤트도 확인하세요. 미해결 오류 없이 턴이 끝나면 아티팩트를 나열하고 생성된 PPTX를 선택합니다.
curl --fail-with-body -sS "$KIMI_BASE/artifacts?session_id=$SESSION_ID" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o artifacts.json &&
jq . artifacts.json &&
read -rp "PPTX artifact ID: " ARTIFACT_ID &&
test -n "$ARTIFACT_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/artifacts/$ARTIFACT_ID/content" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o northstar.pptx &&
printf 'Downloaded northstar.pptx\n'
northstar.pptx를 여세요. 성공적인 결과물은 3개의 슬라이드로 구성되며, 데이터가 허구임을 명시하고, 주간 활동을 90 ÷ 120 = 75%로 계산합니다. 이는 실제 데이터 연결 전에 파일 전달과 콘텐츠 정확성을 모두 구체적으로 점검할 수 있게 해줍니다.
How to Upload and Attach Files to a Kimi Hosted Agents Session?
첫 프레젠테이션이 동작한 뒤, 터미널 A의 작업 디렉터리에 샘플 report.pdf를 놓습니다. 파일 API는 파일 업로드와 세션에 첨부하는 과정을 분리합니다. 첫 작업이 끝난 뒤 기존 세션 ID로 이 블록을 실행하세요.
PDF에서 텍스트를 추출하려면 purpose=file-extract를 사용합니다. 파일 API는 파일당 최대 100 MiB를 허용하며 조직당 기본 10 GiB 저장 용량을 제공합니다. 업로드된 파일은 제자리 업데이트가 불가합니다. 수정된 파일을 업로드하고 새 ID를 바인딩하세요. 저장 공간이 필요하면 사용하지 않는 파일을 제거하세요.
kimi-api-version: 2026-09-01-beta에서는 업로드 응답의 extract_status를 확인하세요. 이 예시는 상태가 ready일 때만 진행합니다. error라면 PDF 형식과 콘텐츠를 점검하고 수정된 파일을 업로드하세요. API는 실패한 추출을 원시 파일로 첨부할 수 있지만, 이 튜토리얼이 기대하는 추출 텍스트는 제공하지 않습니다. 상태가 누락되었거나 예상과 다르면 이 블록을 중단합니다. 계속하기 전에 upload.json을 확인하세요.
test -f report.pdf &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/files" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-F "file=@report.pdf" \
-F "purpose=file-extract" \
-o upload.json &&
FILE_ID="$(jq -er '.id | strings | select(length > 0)' upload.json)" &&
{
EXTRACT_STATUS="$(jq -r '.extract_status // "missing"' upload.json)" &&
case "$EXTRACT_STATUS" in
ready) true ;;
error)
printf '%s\n' 'PDF extraction failed. Check the PDF and upload a corrected file.' >&2
false ;;
*)
printf 'Unexpected extract_status: %s. Inspect upload.json before continuing.\n' "$EXTRACT_STATUS" >&2
false ;;
esac
} &&
jq -n --arg file "$FILE_ID" \
'{type:"file",file_id:$file}' > resource-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/resources" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @resource-request.json
파일 첨부는 새 작업을 보내지 않습니다. 터미널 B 연결을 유지하고, 문서 이름과 원하는 출력을 지정하는 후속 요청을 제출하세요.
jq -n --arg prompt \
"Use the attached report.pdf to create a new three-slide PPTX. Replace the earlier fictional brief. Summarize the report, its evidence, and its next steps. Do not invent missing figures or browse the web. Register the finished PPTX with save_artifact." \
'{events:[{type:"user.message",data:{content:[{type:"text",text:$prompt}]}}]}' \
> followup.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @followup.json
이 작업이 끝나면 아티팩트 목록 조회 단계를 반복하고 새 PPTX를 선택하세요. 특히 수치, 날짜, 제안된 액션이 PDF와 일치하는지 비교하세요.
How Do You Connect Tools to Kimi Hosted Agents?
애플리케이션이 실행하는 커스텀 도구
프로젝트 납기 상태 조회 같은 비즈니스 액션은 애플리케이션이 구현한 커스텀 도구를 사용하세요. 도구를 선언하면 에이전트가 사용할 수 있게 되며, 실제 동작은 여러분의 코드가 수행합니다.
- 에이전트의
tools배열에 이름, 설명, 객체 형태의input_schema가 포함된custom항목을 선언하세요. - 이벤트 스트림에서
agent.custom_tool_use를 처리하고 제공된 인자를 검증한 뒤 함수를 실행하세요. - 호출 이벤트의 JSON
id를data.event_id로 사용하여user.custom_tool_result이벤트를 세션에 게시하세요.
처음에는 읽기 전용 조회부터 시작하세요. 통합이 비즈니스 레코드를 수정할 수 있는 경우, 애플리케이션에서 권한 부여와 중복 액션 방지를 유지하세요.
MCP 서비스와 더 큰 워크플로우
원격 MCP 서비스의 경우 mcp_servers에 연결을 선언하세요. 접근 자격 증명은 금고에 저장하고 세션 생성 시 해당 금고를 바인딩합니다. 플랫폼은 서비스의 도구를 발견하고 호출합니다. 서버 정의에는 비밀 정보 대신 연결 세부 정보가 포함되어야 합니다.
선택적 멀티 에이전트 오케스트레이션
플랫폼은 코디네이터-자식 위임을 지원합니다. 코디네이터는 제한된 작업을 자식 스레드에 할당하고 결과를 결합할 수 있습니다.
위임 구성은 에이전트 항목을 최대 1–20개까지 허용합니다. 이는 구성 한도이며, 20개의 동시 작업자나 20배 속도 향상을 의미하지 않습니다. 자식 스레드는 또 다른 자식 스레드 레이어를 생성할 수 없습니다.
유용한 설계로는 소스 수집, 정량 분석, 편집 검토를 분리하는 방법이 있습니다. 짧은 요약 작업은 보통 하나의 에이전트가 더 적합합니다.
How Should You Deploy a Kimi Hosted Agents Integration?
Kimi API 호출은 애플리케이션 백엔드 뒤에 두세요. 브라우저는 자체 엔드포인트를 통해 작업을 제출하고 진행 상황을 표시하며, 백엔드는 API 키를 보관하고 각 사용자를 해당 사용자가 접근 가능한 세션에 매핑합니다. 세션 ID를 비즈니스 요청과 함께 저장하여 페이지를 새로고침해도 동일한 작업을 다시 열 수 있게 하세요.
Hosted vs. Self-Hosted Execution
이 가이드의 PPT 워크플로우에는 클라우드 환경을 사용하세요. save_artifact와 세션 파일 워크플로우를 지원합니다. 샌드박스 실행을 조직이 관리하는 호스트에서 수행해야 한다면 셀프 호스티드 환경을 선택하세요. Kimi는 여전히 모델 추론, 오케스트레이션, 세션 관리를 수행하며, 도구 입력과 결과는 플랫폼을 통해 전달됩니다. 이는 하이브리드 실행 모델입니다.
- 셀프 호스티드 환경은 엔터프라이즈 검증이 필요합니다. 여러분은 Worker 호스트를 운영하고, 종속성을 설치하며, 격리와 자격 증명을 관리합니다. Worker는 플랫폼으로의 아웃바운드 HTTPS 접근이 필요합니다.
- 셀프 호스티드 모드에는 현재
save_artifact, IPython, 이미지 검색 도구가 없습니다. 업로드 파일, 스킬, 메모리는 Worker에 마운트되지 않으며, Worker의 출력 파일은 세션 파일 목록에 나타나지 않습니다. 본 튜토리얼을 해당 모드로 옮기기 전에 입력 제공과 출력 수집 방법을 계획하세요.
첫 통합에서는 클라우드부터 시작하세요. 실행 호스트에 대한 통제가 추가 설정과 파일 전달 변경을 정당화할 만큼 중요할 때 셀프 호스팅을 고려하세요.
런타임 운영 주체 선택
세션 실행을 플랫폼이 관리하길 원한다면 Hosted Agents를 사용하세요. 팀이 자체 에이전트 루프를 구축·운영해야 한다면, CometAPI provides unified model API access는 해당 맞춤 스택을 위한 통합 모델 API 접근을 제공합니다. 이 가이드의 Hosted Agents 예시는 Kimi의 자체 엔드포인트와 자격 증명을 사용합니다.
Kimi Hosted Agents Pricing and Cost Optimization
Kimi Hosted Agents의 과금은 모델 토큰, 클라우드 샌드박스 런타임, 유료 플러그인 호출에 대해 부과됩니다. 아래 표는 프레젠테이션 워크플로우에 비용이 어떻게 반영되는지 보여줍니다. 가격은 중국 위안(CNY) 기준이며, 2026년 11월 10일에 Hosted Agents pricing과 model inference pricing을 확인했습니다. 100만 토큰은 1 MTok입니다.
| 비용 구성요소 | 과금 단위 | 요율 및 작업에 대한 의미 |
|---|---|---|
| 모델 추론 | 1 MTok당 | kimi-k3.1-pro의 경우: 기본 입력 ¥13, 출력 ¥68, 캐시 적중 ¥1.30, 5분 캐시 기록 ¥13, 1시간 캐시 기록 ¥26. 모든 모델 호출에 대해 각 사용 범주별 요율을 적용합니다. |
| 클라우드 샌드박스 | 런타임; 초 단위 과금 | 1 CPU 코어, 1 GB 메모리 샌드박스 기준 ¥0.072/시간. 10분은 ¥0.012입니다. |
| 플러그인 | 유료 호출당 | 예: 웹 검색 ¥0.03/회; 이미지 검색 ¥0.045/회. 다른 플러그인은 자체 요율이 있습니다. 각 플러그인의 호출 수에 해당 가격을 곱하세요. |
| 작업 총비용 | 완료된 작업당 | 모델, 샌드박스, 플러그인 비용을 합산합니다. 아래의 PPT 예시는 유료 플러그인 호출 없이 총 ¥0.544, 동일한 모델 사용량과 런타임에서 웹 검색 3회와 이미지 검색 2회를 포함하면 ¥0.724입니다. |
모델 요율은 kimi-k3.1-pro에 대한 예산 편성 예시이며, 모든 공식 PPT 에이전트가 해당 모델을 사용한다는 주장은 아닙니다. 이러한 요율을 적용하기 전에 선택한 에이전트의 모델 정의를 확인하세요. 다른 모델 및 고속 변형의 요율은 다릅니다.
입력 및 출력 토큰을 계산하는 방법
에이전트는 하나의 프레젠테이션을 만드는 동안 모델을 여러 번 호출할 수 있습니다. 후속 턴과 수정 작업을 포함하여 모든 호출의 과금 사용량을 합산하세요. 입력에는 프롬프트, 추출된 PDF 텍스트, 도구 결과, 대화 컨텍스트 등이 포함될 수 있으며, 출력 사용량은 슬라이드에 보이는 단어로만 제한되지 않습니다.
K3 캐싱의 경우, 비캐시 입력, 캐시 기록, 캐시 적중을 구분하세요. 이들은 별개의 입력 범주입니다. 동일한 토큰에 대해 전체 입력 총량을 기본 요율로 과금하고 캐시 요금을 추가로 더하지 마세요. 해당하는 5분 또는 1시간 기록 요율을 사용하세요. 캐시 과금 가이드는 보고된 사용량과 이 범주를 대조하는 방법을 설명합니다.
예시 계산: 3장짜리 프레젠테이션
에이전트가 kimi-k3.1-pro를 사용하고, 완전한 3장짜리 PPT 실행이 20,000 입력 토큰, 4,000 과금 출력 토큰, 과금되는 클라우드 런타임 10분을 소비한다고 가정합니다. 캐시 적중, 1시간 캐시 기록, 유료 플러그인 호출은 없다고 가정합니다. 모든 입력은 비캐시 또는 기본 5분 캐시에 기록되며 둘 다 ¥13/MTok로 가격 책정됩니다. 이는 Northstar 튜토리얼의 계측값이 아닌, 계획을 위한 추정 사용량입니다.
| 과금 항목 | 계산식 | 추정 비용 |
|---|---|---|
| 모델 입력 | 20,000 ÷ 1,000,000 × ¥13 | ¥0.260 |
| 모델 출력 | 4,000 ÷ 1,000,000 × ¥68 | ¥0.272 |
| 클라우드 샌드박스 | 10 ÷ 60 × ¥0.072 | ¥0.012 |
| 유료 플러그인 | 0건 | ¥0.000 |
| 합계 | ¥0.260 + ¥0.272 + ¥0.012 | ¥0.544 (약 ¥0.54) |
제공된 사실만 사용하도록 한 튜토리얼은 에이전트가 웹을 탐색하지 않도록 요구합니다. 이후 이를 리서치 프레젠테이션으로 확장하여 웹 검색 3회, 이미지 검색 2회를 수행하면 플러그인 비용은 3 × ¥0.03 + 2 × ¥0.045 = ¥0.180입니다. 다른 수치를 동일하게 유지하면 ¥0.544 + ¥0.180 = ¥0.724가 됩니다. 리서치는 모델 토큰과 런타임도 증가시킬 수 있으므로 최종 청구에는 계측된 사용량을 사용하세요.
여러 에이전트를 사용할 때 무엇이 달라지나요?
위임은 모델 호출, 반복된 컨텍스트, 도구 호출, 수정 작업을 추가할 수 있습니다. Kimi의 멀티 에이전트 워크플로우는 코디네이터와 자식 스레드를 하나의 세션에 배치합니다. 자식 스레드 수만으로 샌드박스 비용이 곱절로 늘어나지는 않습니다. 스레드 전반의 모델 및 플러그인 사용량을 합산하고, 세션의 실제 과금 런타임을 사용하세요. 더 긴 실행 또는 추가 독립 클라우드 세션은 샌드박스 비용을 증가시킬 수 있습니다. FAQ는 모든 스레드가 종료되어 세션이 idle이 되면 샌드박스 시간이 누적을 멈춘다고 설명합니다.
사용 가능한 프레젠테이션당 비용 절감
하나의 에이전트와 작은 결과물부터 시작하세요. 관련 소스 문장을 제공하고, 슬라이드 수를 제한하며, 필요한 경우에만 유료 검색을 활성화하세요. 동일 작업을 다시 제출하는 대신 끊어진 이벤트 스트림을 재연결하세요. 반복 워크플로우에서는 캐시 적중을 점검하고 재사용 가능한 컨텍스트를 안정적으로 유지하세요. 모든 시도에 든 총비용과 실제로 수용한 프레젠테이션 수를 비교하세요. 여러 번 재실행이 필요한 값싼 초안은 전체적으로 더 비쌀 수 있습니다.
Troubleshooting Common API Errors
- 인증 실패: 요청을 보내는 터미널에 API 키가 설정되어 있고 의도한 계정에 속하는지 확인하세요. 호출을 반복하기 전에 HTTP 오류를 점검하세요.
- curl 옵션 거부 또는 jq 누락: 설치된 유틸리티를 확인하세요. 이 예시는
--fail-with-body를 지원하는 curl 버전과 동일 Bash 환경에서 동작하는 jq 실행 파일이 필요합니다. - jq로 ID 추출 불가: 저장된 응답 JSON을 여세요. 성공 리소스 객체 대신 API 오류가 포함되어 있을 수 있습니다. 다음 엔드포인트에 빈 ID를 전달하기보다 먼저 요청을 수정하세요.
- 커스텀 도구 워크플로우가 진행되지 않음: 보류 중인 도구 이벤트를 점검하세요.
requires_action중단 이유는 클라이언트가 도구 결과를 반환하거나 확인을 처리해야만 해당 스레드가 계속된다는 의미입니다. - 다운로드한 슬라이드에 근거 없는 주장 포함: 제공된 브리프나 보고서와 비교하세요. 특정 불일치 사항으로 작업을 수정하고 다음 결과물을 점검한 뒤 사용하세요.
실패를 진단할 때는 엔드포인트, HTTP 상태, 세션 ID, 관련 이벤트를 기록하세요. 진단 로그에는 API 키를 남기지 마세요.
Conclusion
완전한 Kimi Hosted Agents 워크플로우 하나로 시작하세요. 에이전트를 선택하고, 환경을 준비하며, 세션을 만들고, 작업을 제출하고, 전달된 파일을 점검합니다. 이 경로가 동작하면 소스 문서를 추가하고 애플리케이션에 필요한 비즈니스 도구를 연결하세요. 진행 상황을 가시화하고 요청 성공 여부가 아니라 출력의 유용성으로 각 실행을 평가하세요.
FAQ
연결이 끊긴 후 Kimi Hosted Agents 작업을 다시 보내야 하나요?
아니요. 이벤트 스트림 연결이 끊겨도 새 작업 제출은 필요하지 않습니다. 다시 읽기 위해 마지막 SSE 프레임의 id: 값을 Last-Event-ID 헤더에 넣어 재연결하세요. 이 값은 스트림 커서이며, 이벤트 객체의 JSON ID가 아닙니다. 재연결하면 동일 작업을 실수로 두 번 제출하는 일을 피할 수 있습니다.
Kimi Hosted Agents 출력이 아티팩트에 없으면 어떻게 하나요?
샌드박스 파일은 아티팩트로 등록되지 않아도 존재할 수 있습니다. 에이전트가 프레젠테이션을 완료하고 save_artifact를 호출했는지 확인하세요. 등록이 누락된 경우 세션 파일 API로 출력 디렉터리를 점검하세요: GET /v1/sessions/{session_id}/filesystem?prefix=output. 목록은 한 디렉터리만 다루므로, 하위 디렉터리를 점검하려면 prefix를 업데이트하세요. 목록에서 반환된 정확한 경로로 GET /v1/sessions/{session_id}/filesystem/raw?path=output/northstar.pptx를 사용해 선택한 파일을 다운로드하세요. 경로에 공백이나 예약 문자가 있으면 쿼리 값을 URL 인코딩하세요. 튜토리얼과 동일한 인증 및 API 버전 헤더를 포함하세요.
Kimi Hosted Agents 구성을 업데이트하면 활성 세션이 변경되나요?
아니요. 세션은 생성 시 고정된 에이전트 버전을 사용합니다. 에이전트를 업데이트하면 이후 세션을 위한 새 버전이 생성되지만, 기존 세션은 원래 구성을 유지합니다. 수정된 지시문이나 도구를 시험하려면 새 세션을 시작하고 이전 실행과 출력을 비교하세요.

