> ## Documentation Index > Fetch the complete documentation index at: https://ppio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > PPIO model APIs are OpenAI-compatible. Base URL: https://api.ppio.com/openai. Anthropic-compatible base URL: https://api.ppio.com/anthropic. > Authenticate with `Authorization: Bearer `; with Anthropic SDKs or Claude Code, pass the same key as `ANTHROPIC_AUTH_TOKEN`. Users create keys at https://ppio.com/settings/key-management. Never print or hardcode a real key. > Get current model IDs from GET https://api.ppio.com/openai/v1/models instead of reusing model names from memory. # Kimi Hosted Agents > 查阅 Kimi Hosted Agents API 接入 PPIO Agent 沙箱的说明，了解自托管环境、控制器部署与会话执行流程，为智能体应用连接云端执行能力提供参考。 Kimi Hosted Agents API 让应用通过 Kimi 托管的接口运行 Agent。Kimi 负责管理会话、任务编排与上下文状态；应用只需要创建会话、发送输入，并为 Agent 指定一个自托管的执行环境。 Agent 可以运行在 PPIO Sandbox 中，在沙箱里执行命令、修改文件并生成产物。完整的 API 说明请参阅 [Kimi Hosted Agents 官方文档](https://platform.kimi.com/docs/hosted-agents/overview.md)。 ```mermaid theme={null} flowchart LR App["应用
webhook:client"] -->|创建会话 · 发送输入| Kimi["Kimi Hosted Agents API
会话 · 工作队列"] subgraph PPIO["PPIO Sandbox"] direction TB Controller["控制器
webhook:deploy"] -->|创建 · 恢复| Worker["worker
kha worker run
每个会话一个"] end Controller -->|轮询 · 领取工作项| Kimi Worker -->|执行工具调用 · 回传结果| Kimi ``` 沙箱内所有连接均为出站，没有任何入站端口。 *** ## 前置条件 ### 克隆 executor 仓库 克隆仓库，其中包含你后续要部署的控制器与客户端： ```bash theme={"system"} theme={null} git clone https://github.com/PPIO/kimi-agents-api-executor.git cd kimi-agents-api-executor cp .env.example .env npm install ``` ### 环境变量 * **PPIO\_API\_KEY** —— 在 [PPIO 控制台](https://ppio.com/settings/key-management)获取 API key。 * **KIMI\_API\_KEY** —— 在 [Kimi 开放平台](https://platform.kimi.com/console/account)的 API keys 页面创建。 * **KIMI\_ENVIRONMENT\_ID** —— [创建环境](#创建环境)一节里 `--create-environment` 打印的 ID。 * **KIMI\_ENVIRONMENT\_KEY** —— 在 Kimi 控制台该环境的 **Worker** 标签页生成的环境密钥，见[申请环境 Key](#申请环境-key)。 * **KIMI\_AGENT\_ID** —— [创建 Agent](#创建-agent)一节里 `--create-agent` 打印的 ID。 详情参阅 Kimi 的[自托管环境说明](https://platform.kimi.com/docs/hosted-agents/self-hosted-environments.md)。 *** ## 创建自托管环境 ### 创建环境 环境只需创建一次，而不是每个会话都创建： ```bash theme={"system"} theme={null} npm run webhook:client -- --create-environment ppio-executor ``` 它会打印新的环境 ID，并提示你去生成工作密钥： ```json theme={"system"} theme={null} {"environment_id":"env_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","note":"generate a work key on this environment's Worker tab in the console and set KIMI_ENVIRONMENT_KEY"} ``` 将该 ID 填入 `.env` 的 `KIMI_ENVIRONMENT_ID`。 ### 申请环境 Key 在 [Kimi 控制台](https://platform.kimi.com/console)**进入项目**，依次打开 **托管智能体** › **环境**，**选择刚刚创建的环境**，点击 **生成环境密钥**。把生成的密钥（`ewk-...`）填入 `.env` 的 `KIMI_ENVIRONMENT_KEY`。 ![在 Kimi 控制台环境的 Worker 标签页生成环境密钥](https://mintcdn.com/ppinfra/o2r463918bHdQRki/images/sandbox/kimi-agents-api-environment-key.png?fit=max\&auto=format\&n=o2r463918bHdQRki\&q=85\&s=acba5e10f846a7189f478bf8569b2c89) *** ## 创建 Agent 创建控制器将要服务的 Agent： ```bash theme={"system"} theme={null} npm run webhook:client -- --create-agent coding-assistant ``` 它会打印新的 Agent ID，例如： ```json theme={"system"} theme={null} {"agent_id":"agent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} ``` 将该 ID 填入 `.env` 的 `KIMI_AGENT_ID`。 *** ## 部署控制器 > [!WARNING] > > 控制器运行在一个[长时运行](https://ppio.com/docs/sandbox/sandbox-long-running.md)的 Sandbox 中，会常驻并持续计费。不使用时请手动暂停或关闭该沙箱，否则会一直产生费用。沙箱 ID 保存于 `.controller.json`。 ```bash theme={"system"} theme={null} npm run webhook:deploy ``` 它会在一个 PPIO Sandbox 中运行控制器，并打印健康检查 URL： ```text theme={"system"} theme={null} Reusing controller sandbox Health: https://8000-.cn-beijing-1.sandbox.ppio.com/healthz Controller log: /app/controller.log (inside ) The controller is now polling environment . Sanity check: curl -s https://8000-.cn-beijing-1.sandbox.ppio.com/healthz expects {"ok":true,...}. Nothing needs registering with Kimi. ``` ![npm run webhook:deploy 的输出](https://mintcdn.com/ppinfra/o2r463918bHdQRki/images/sandbox/kimi-agents-api-deploy.png?fit=max\&auto=format\&n=o2r463918bHdQRki\&q=85\&s=08484b4b59dd01514d783448db7b7e73) 无需在 Kimi 侧注册任何东西，控制器启动后立即开始轮询环境。确认它在运行： ```bash theme={"system"} theme={null} curl -s # {"ok":true,"inFlight":0} ``` 控制器的沙箱 ID 保存于 `.controller.json`。重新运行 `webhook:deploy` 会重新连接到同一控制器，并用新的环境变量重启它。不使用时，用该 ID 暂停或关闭控制器沙箱： ```bash theme={"system"} theme={null} ppio sandbox pause # 暂停，保留状态 ppio sandbox kill # 关闭并销毁 ``` *** ## 发送输入 通过客户端向 Agent 发送消息，客户端与运行在 worker 沙箱中的 Agent 通信： ```bash theme={"system"} theme={null} npm run webhook:client -- --input "查看一下我操作系统的运行环境" ``` 输出的第一行是会话 ID，形如 `{"session_id":"sesn_..."}`。Agent 的输出会随着生成实时流出，会话回到 `idle` 后命令退出。 如果配置正确，Agent 描述的会是**沙箱内**的环境，而非你的本机 —— 例如下面的 Debian GNU/Linux 12 (Bookworm)、内核 Linux 6.1.158、x86\_64，工作目录 `/workspace` —— 这确认了会话通过 PPIO 托管的 worker 执行，你无需创建或注册任何自己的沙箱。 ![Agent 回报沙箱内运行环境的输出](https://mintcdn.com/ppinfra/o2r463918bHdQRki/images/sandbox/kimi-agents-api-output.png?fit=max\&auto=format\&n=o2r463918bHdQRki\&q=85\&s=6af31ef4d0d842d7f37a4e2ad2762243) 将会话 ID 通过 `--session-id` 传回即可在同一 worker、同一工作区继续： ```bash theme={"system"} theme={null} npm run webhook:client -- --session-id "$SESSION_ID" --input "再次执行" ``` > [!NOTE] > > Sandbox 的文件系统与沙箱绑定，会随沙箱一起销毁。如果你希望代码与数据在沙箱之外留存、并可被其他 Agent 读取，请用 Git 管理代码，或挂载 [Volume](https://ppio.com/docs/sandbox/volume-overview.md) 将数据保存在沙箱之外并在多个沙箱间共享。 *** ## 排查 ### 日志与状态 * **控制器日志**：控制器沙箱内的 `/app/controller.log`，JSON 行格式，事件包括 `enqueued`、`ack_failed`、`worker_created`、`worker_resumed`、`executor_started`、`worker_paused`、`claim_resolved`、`work_reread_failed`、`reconcile_failed`、`poll_failed` 等。进程崩溃的堆栈写入 `/app/controller.stdio.log`。 * **worker 日志**：每个 worker 内的 `/tmp/kha-worker.log`。租约与工具调用失败都在这里，而不是在任何 HTTP 状态码中。 * **工作队列**：`GET /v1/environments/$KIMI_ENVIRONMENT_ID/work` 列出每个工作项的状态与 `worker_id`；`/work/stats` 返回队列深度与 worker 数量。 * **元数据**：worker 沙箱带有 `agents-session-id=`，控制器沙箱带有 `agents-webhook-controller=ppio`。 ### 常见问题 | 现象 | 检查 | | - | - | | 创建环境返回 `403 permission_denied_error` | 账号未开通自托管功能。携带 `request_id` 联系 Kimi。 | | 工作项一直处于 `queued` | 控制器是否存活（`curl` 健康检查 URL）？控制器中的 `KIMI_ENVIRONMENT_ID` 是否与会话绑定的一致？如果限制了出网，需放行 `api.moonshot.cn`。 | | 控制器日志出现 `poll_failed` 且状态码 `401` | 工作密钥已吊销，或属于另一个环境。在 Worker 标签页重新生成并重新部署。 | | `ack_failed` 且状态码 `412` | 控制器未能在 ack 窗口内响应。通常是控制器沙箱资源不足，检查其负载。 | | worker 在约 61 秒时退出 | 某个 `commands.run` 启动时未设置 `background: true`。 | | 每个工作项都出现 `claim_resolved` | 租约在核对前被回收。同一环境上有另一个轮询方，或 `LEASE_TTL_MS` 过短。 | | `session.error` | 读取 worker 日志。工具调用失败在那里，而不是在 HTTP 状态中。 | | `enqueued` 成功后 `reconcile_failed`，报 `auth user unauthorized: invalid token` | 控制器连到了错误的 PPIO 区域：shell 中设置了 `PPIO_DOMAIN`，但部署的控制器没拿到。检查 `controller_listening` 日志行中的 `ppioDomain`，然后重新部署。 | | 所有 SDK 调用都返回 503 与 HTML 响应体 | `PPIO_DOMAIN` 设置为 SDK 不识别的区域。请不要设置它。 | | Agent 报告成功但文件缺失 | 请以沙箱文件系统为准做断言，而不是最终回复。 | | `ppio sandbox exec` 挂起且无输出 | 非交互式 stdin 被当作管道输入等待。脚本中的每个 `exec` 都加上 `