TL;DR
Kimi Hosted Agents runs multi-step AI tasks with persistent sessions, tool execution, and cloud sandboxes. This guide takes you from a Kimi API key to a downloadable three-slide presentation using Bash, curl, and jq. First complete one task with a self-contained prompt. Then add an uploaded document, connect business tools, and handle the failures that matter in a deployed application.
Key Takeaways
- Kimi Hosted Agents connects an agent definition, an execution environment, and a session. Keep their IDs available throughout the workflow.
- Start with a small, verifiable result. The first example produces a presentation with fictional data and a calculation you can check.
- Use the event stream to follow execution, then inspect the delivered file. A successful HTTP response alone does not establish task success.
- Extend the working example with file inputs, custom tools, or MCP services. Each integration has its own execution and credential requirements.
- Budget for inference, sandbox runtime, and plugin usage together, including reruns needed to produce an acceptable result.
What Is Kimi Hosted Agents?
Moonshot AI announced Kimi Hosted Agents on November 5, 2026, positioning it as a service for enterprises and developers building long-running agents.
The product uses a Harness as a Service approach. A harness is the software around a model that manages how work progresses: maintaining state, invoking tools, managing execution, and recovering from interruptions.
Consider a weekly research workflow. Generating text is only one step. The application may also need to retrieve sources, process files, create charts, save a presentation, and preserve enough state to continue after a disconnect.
Hosted Agents supplies that operational layer. Your team still defines the business task, selects integrations, and decides what constitutes an acceptable result.
Kimi’s official architecture shows the application, platform services, and execution core used by the hosted runtime.
Core capabilities for your first integration
- Persistent sessions keep a task’s inputs, execution events, and outputs together.
- Cloud sandboxes provide the tools needed to process files and create deliverables.
- Skills and plugins package reusable capabilities; custom tools and MCP services connect your own systems.
Your first checkpoint is a presentation you can open and inspect. Detailed runtime specifications become useful when you add dependencies or move an existing workflow into the sandbox; the sandbox reference documents the available environment.
What Do You Need Before Calling the Kimi Hosted Agents API?
- A Kimi platform account with access to Hosted Agents and an API key.
- Bash, curl, and jq on macOS, Linux, or Windows with WSL.
- Two terminals: Terminal A sends requests; Terminal B watches execution events.
- A presentation viewer to open the generated PPTX.
Create a Kimi platform account and an API key in the console’s API management area. Use one Bash terminal, called Terminal A, for the setup and task commands. Keep it open so later steps can reuse its variables. Install curl and jq before continuing. The examples use the beta API version 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
The workflow follows Kimi’s REST API quickstart. You will use the official PPT assistant to turn a short fictional business brief into a presentation. All input data is included in the request, so the first run needs no file upload or private data connection.
Run each block in order and check its output before continuing. Commands joined by && stop that block when a request or validation fails. Resolve the reported error before moving to the next step; keep the same environment and session IDs when retrying an existing setup.
Step 1: Select the official PPT assistant
Fetch the available agents and inspect their names and definitions. When prompted, paste the ID of the official PPT assistant configured with PPT skills. The final command checks that your selection exists in the returned list and prints its definition.
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
The final command should print the selected agent’s definition. If the assistant is not available in your project, use the official PPT agent configuration to prepare an equivalent agent before continuing.
Step 2: Create a cloud environment
An Environment is a reusable configuration for your execution setup, including installed packages, network access, and startup commands. Reusing it gives later sessions the same setup; each cloud session still receives its own sandbox and workspace. See the environment guide for configuration options.
Create the environment once and keep its ID. Cloud images build asynchronously, so wait until its build status is ready before creating a session. If the API reports that it is not ready, wait and retry with the same ENVIRONMENT_ID. Creating another environment does not finish the first build.
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: Create a session
A Session fixes the Agent version and an available Environment version when it is created. The request below supplies their IDs; the platform selects and freezes the versions. You can also set agent_version to choose an exact Agent version. Updating the Agent or Environment later does not update an existing session, and a session cannot switch its environment_id. Create a new session to use revised configurations. These rules are documented in session creation.
Keep the returned session ID for both the event stream and task requests. A new session starts in idle; sending user.message starts the task.
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: Watch execution in a second terminal
Open Terminal B. Enter the same API key, then paste the session ID printed in Terminal A. The server-sent event stream displays execution updates while Terminal A submits the task. Leave this terminal connected until you have inspected the result.
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: Send a self-contained task
Return to Terminal A and send a user.message event. The example uses fictional figures and asks for a specific deliverable. The agent should use the supplied facts rather than search for supporting business data.
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: Download and inspect the presentation
Watch Terminal B for session.status events. When the session returns to idle, inspect its stop reason: end_turn indicates that the turn has finished, while requires_action means your client must supply a tool result or handle a confirmation. Check session.error events as well. After the turn finishes without an unresolved error, list the artifacts and select the generated 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'
Open northstar.pptx. A successful result has three slides, identifies the data as fictional, and calculates weekly activity as 90 ÷ 120 = 75%. This gives you a concrete check of both file delivery and content accuracy before connecting real business data.
How to Upload and Attach Files to a Kimi Hosted Agents Session?
After the first presentation works, place a sample report.pdf in Terminal A’s working directory. The file API separates uploading a file from attaching it to a session. Run this block with the existing session ID after the first task has finished.
Use purpose=file-extract to extract text from the PDF. The file API allows up to 100 MiB per file and defaults to 10 GiB of storage per organization. Uploaded files cannot be updated in place; upload a revised file and bind its new ID. Remove unused files when you need to free storage.
With kimi-api-version: 2026-09-01-beta, check extract_status in the upload response. This example proceeds only when it is ready. If it is error, inspect the PDF format and contents, then upload a corrected file. The API can attach a failed extraction as a raw file, but that does not provide the extracted text this tutorial expects. A missing or unexpected status also stops the block; inspect upload.json before continuing.
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
Attaching the file does not send a new task. Keep Terminal B connected and submit a follow-up that names the document and the desired output.
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
When this task finishes, repeat the artifact-listing step and select the new PPTX. Compare its claims with the PDF, especially any numbers, dates, and proposed actions.
How Do You Connect Tools to Kimi Hosted Agents?
Custom tools executed by your application
For a business action such as looking up a project’s delivery status, use a custom tool implemented by your application. Declaring the tool makes it available to the agent; your code still performs the operation.
- Declare a
customentry in the agent’stoolsarray with a name, description, and object-shapedinput_schema. - Handle
agent.custom_tool_usefrom the event stream and validate the supplied arguments before executing your function. - Post a
user.custom_tool_resultevent to the session, using the calling event’s JSONidasdata.event_id.
Start with a read-only lookup. Keep authorization and duplicate-action protection in the application when an integration can modify business records.
MCP services and larger workflows
For a remote MCP service, declare its connection in mcp_servers. Store access credentials in a vault and bind that vault when creating the session. The platform discovers and calls the service’s tools; the server definition should contain connection details rather than secrets.
Optional multi-agent orchestration
The platform supports coordinator-to-child delegation. A coordinator can assign bounded tasks to child threads and combine their results.
Its delegation configuration accepts 1–20 agent entries. This is a configuration limit, not evidence of 20 simultaneous workers or a 20× speed improvement. Child threads cannot create another layer of child threads.
A useful design might separate source collection, quantitative analysis, and editorial review. A short summarization task is usually better handled by one agent.
How Should You Deploy a Kimi Hosted Agents Integration?
Put Kimi API calls behind your application’s backend. The browser can submit a task and display progress through your own endpoints, while the backend keeps the API key and maps each user to the sessions they are allowed to access. Store the session ID with the business request so a page reload can reopen the same task.
Hosted vs. Self-Hosted Execution
Use a cloud environment for the PPT workflow in this guide: it supports save_artifact and the session file workflow. Choose a self-hosted environment when sandbox execution must run on a host your organization manages. Kimi still runs model inference, orchestration, and session management; tool inputs and results pass through its platform. This is a hybrid execution model.
- Self-hosted environments require enterprise verification. You operate the Worker host, install its dependencies, and manage isolation and credentials. The Worker needs outbound HTTPS access to the platform.
- Self-hosted mode currently lacks
save_artifact, IPython, and image-search tools. Uploaded files, skills, and memory are not mounted on the Worker, and its output files do not appear in the session file list. Plan how to supply inputs and retrieve outputs before moving this tutorial to that mode.
For a first integration, start in the cloud. Consider self-hosting when control over the execution host justifies the additional setup and changes to file delivery.
Choosing who operates the runtime
Use Hosted Agents when you want the platform to manage session execution. If your team needs to build and operate its own agent loop, CometAPI provides unified model API access for that custom stack. The Hosted Agents examples in this guide use Kimi’s own endpoints and credentials.
Kimi Hosted Agents Pricing and Cost Optimization
Kimi Hosted Agents charges for model tokens, cloud sandbox runtime, and paid plugin calls. The table below shows how those charges affect a presentation workflow. Prices are in Chinese yuan (CNY), checked on November 10, 2026 against Hosted Agents pricing and model inference pricing. One million tokens equals 1 MTok.
| Cost component | Billing unit | Rate and what it means for your task |
|---|---|---|
| Model inference | Per 1 MTok | For kimi-k3.1-pro: base input ¥13, output ¥68, cache hits ¥1.30, 5-minute cache writes ¥13, and 1-hour cache writes ¥26. Apply the rate for each usage category across all model calls. |
| Cloud sandbox | Runtime; billed by the second | ¥0.072/hour for a sandbox with 1 CPU core and 1 GB memory. Ten minutes costs ¥0.012. |
| Plugins | Per billable call | Examples: web search ¥0.03/call; image search ¥0.045/call. Other plugins have their own rates. Multiply each plugin’s calls by its listed price. |
| Total task cost | Per completed task | Add model, sandbox, and plugin charges. The worked PPT example below totals ¥0.544 without paid plugin calls, or ¥0.724 with three web searches and two image searches at the same assumed model usage and runtime. |
The model rate is a budgeting example for kimi-k3.1-pro, not a claim that every official PPT Agent uses that model. Check the selected Agent’s model definition before applying these rates. Rates for other models and high-speed variants differ.
How to count input and output tokens
An Agent can call its model several times while creating one presentation. Add the billed usage from every call, including follow-up turns and revisions. Input can include the prompt, extracted PDF text, tool results, and conversation context; output usage is not limited to the words visible on the slides.
For K3 caching, separate uncached input, cache writes, and cache hits. These are distinct input categories: do not charge the full input total at the base rate and then add cache charges for the same tokens. Use the applicable 5-minute or 1-hour write rate. The cache billing guide explains how to reconcile these categories with reported usage.
Worked example: a three-slide presentation
Suppose your Agent uses kimi-k3.1-pro and a complete three-slide PPT run consumes 20,000 input tokens, 4,000 billed output tokens, and 10 minutes of billable cloud runtime. Assume no cache hits, no 1-hour cache writes, and no paid plugin calls. All input is either uncached or written to the default 5-minute cache, both priced at ¥13/MTok. These are estimated usage quantities for planning, not measurements of the Northstar tutorial.
| Charge | Calculation | Estimated cost |
|---|---|---|
| Model input | 20,000 ÷ 1,000,000 × ¥13 | ¥0.260 |
| Model output | 4,000 ÷ 1,000,000 × ¥68 | ¥0.272 |
| Cloud sandbox | 10 ÷ 60 × ¥0.072 | ¥0.012 |
| Paid plugins | 0 billable calls | ¥0.000 |
| Total | ¥0.260 + ¥0.272 + ¥0.012 | ¥0.544 (about ¥0.54) |
The supplied-facts tutorial asks the Agent not to browse the web. If you later expand it to a research presentation with three web searches and two image searches, the plugin charge would be 3 × ¥0.03 + 2 × ¥0.045 = ¥0.180. Holding the other quantities constant gives ¥0.544 + ¥0.180 = ¥0.724. Research may also increase model tokens and runtime, so use the measured quantities for the final bill.
What changes when you use multiple agents?
Delegation can add model calls, repeated context, tool calls, and revision work. Kimi’s multi-agent workflow places the coordinator and child threads in one session. Child-thread count alone is not a multiplier for sandbox charges. Sum model and plugin usage across threads, and use the session’s actual billable runtime. Longer execution or additional independent cloud sessions can increase sandbox cost. The FAQ explains that sandbox time stops accumulating when all threads finish and the session becomes idle.
Reduce cost per usable presentation
Begin with one Agent and a small deliverable. Supply the relevant source passages, constrain slide count, and enable paid searches only when the task needs them. Reconnect a dropped event stream instead of submitting the same task again. For repeat workflows, inspect cache hits and keep reusable context stable. Compare the total cost of all attempts with the number of presentations you actually accept; a cheap first draft that needs several reruns may cost more overall.
Troubleshooting Common API Errors
- Authentication fails: check that the API key is set in the terminal sending the request and belongs to the intended account. Inspect the HTTP error before repeating the call.
- curl rejects an option, or jq is missing: check the installed utilities. These examples require a curl version supporting
--fail-with-bodyand a working jq executable in the same Bash environment. - jq cannot extract an ID: open the saved response JSON. It may contain an API error instead of a successful resource object. Fix the request first rather than passing an empty ID to the next endpoint.
- A custom-tool workflow stops progressing: inspect pending tool events. A
requires_actionstop reason means the client needs to return a tool result or handle a confirmation before the affected thread continues. - The downloaded slides contain unsupported claims: compare them with the supplied brief or report. Revise the task with the specific discrepancy and inspect the next deliverable before using it.
Record the endpoint, HTTP status, session ID, and relevant event when diagnosing a failure. Keep API keys out of diagnostic logs.
Conclusion
Begin with one complete Kimi Hosted Agents workflow: select an agent, prepare its environment, create a session, submit a task, and inspect the delivered file. Once that path works, add a source document and then the business tools your application needs. Keep progress visible and judge each run by the usefulness of its output, not just whether the request succeeded.
FAQ
Do I need to resend a Kimi Hosted Agents task after a disconnect?
No. A disconnected event stream does not require a new task submission. Reconnect with the last SSE frame’s id: value in the Last-Event-ID header to resume reading. This value is a stream cursor, not the event object’s JSON ID. Reconnecting avoids accidentally submitting the same work twice.
What if a Kimi Hosted Agents output is missing from artifacts?
A sandbox file can exist without being registered as an artifact. Check whether the agent completed the presentation and called save_artifact. If registration is missing, use the session file APIs to inspect the output directory: GET /v1/sessions/{session_id}/filesystem?prefix=output. The listing covers one directory at a time; update prefix to inspect a subdirectory. Download the chosen file with GET /v1/sessions/{session_id}/filesystem/raw?path=output/northstar.pptx, replacing the example path with the exact path returned by the listing. URL-encode the query value if the path contains spaces or other reserved characters. Include the same authorization and API-version headers as in the tutorial.
Will updating a Kimi Hosted Agents configuration change an active session?
No. A session uses the agent version fixed at creation. Updating the agent creates a new version for subsequent sessions while existing sessions keep their original configuration. To test revised instructions or tools, start a new session and compare its output with the previous run.

