> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过代码编排工具调用

> 在客户端定义代码执行工具，让模型生成 Python 代码在隔离容器中批量调用函数并汇总结果，减少多轮工具调用的往返次数与上下文长度。

当任务需要批量查询数据、跨工具传递参数或对多条记录做筛选汇总时，如果让模型逐步发起普通工具调用，不仅需要多次往返请求，还会把大量原始明细堆进历史消息列表 `messages`。此时可以在客户端定义 `run_code` 工具：让模型编写一段 Python 代码，在隔离容器中循环调用工具函数并完成计算，只将最终汇总结果回传给模型。

## 实现客户端代码执行工具

本示例基于 [工具调用流程](https://platform.kimi.com/docs/guide/use-kimi-api-to-complete-tool-calls.md) 实现。运行前请确保本地已安装 Docker，并在环境变量 `MOONSHOT_API_KEY` 中配置 API Key：

```python expandable theme={null}
import json
import os
import subprocess
from typing import Any
import uuid
from openai import OpenAI

Message = dict[str, Any]
MODEL = "kimi-k3.1-pro"
BASE_URL = "https://api.moonshot.cn/v1"
TIMEOUT_SECONDS = 10

# 容器内预置函数
SANDBOX_TOOLS = '''
ORDERS = {
    "ord_1": {"id": "ord_1", "status": "paid", "amount": 120, "detail": "raw-log-alpha"},
    "ord_2": {"id": "ord_2", "status": "refunded", "amount": 80, "detail": "raw-log-beta"},
    "ord_3": {"id": "ord_3", "status": "paid", "amount": 230, "detail": "raw-log-gamma"},
}

def list_order_ids() -> list[str]:
    return list(ORDERS.keys())

def get_order(order_id: str) -> dict:
    return ORDERS[order_id]
'''

# 代码执行工具定义
RUN_CODE_TOOL: dict[str, Any] = {
    "type": "function",
    "function": {
        "name": "run_code",
        "description": (
            "在隔离的 Python 容器中运行代码，以批量调用查询函数并汇总结果。\n"
            "容器内可直接调用以下只读函数（无需 import）：\n"
            "- list_order_ids() -> list[str]：返回全部订单 ID 列表\n"
            "- get_order(order_id: str) -> dict：返回订单字典，含 id、status（'paid' 或 'refunded'）、amount（int）、detail（str）\n"
            "请只用 print() 输出最终汇总结果，不要打印原始明细。"
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "code": {"type": "string", "description": "要执行的 Python 3 代码，通过 print() 输出最终结果"},
            },
            "required": ["code"],
            "additionalProperties": False,
        },
    },
}


# 请求函数
def complete(messages: list[Message], **parameters: Any) -> dict[str, Any]:
    client = OpenAI(
        api_key=os.environ["MOONSHOT_API_KEY"],
        base_url=BASE_URL,
    )
    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        max_tokens=8192,
        **parameters,
    )
    return response.model_dump()


# 容器执行函数
def run_code(code: str, timeout: int = TIMEOUT_SECONDS) -> str:
    if not code.strip():
        return "Error: code must be a non-empty string"
    container_name = f"kimi-ptc-{uuid.uuid4().hex[:12]}"
    script = f"{SANDBOX_TOOLS}\n{code}"
    try:
        completed = subprocess.run(
            [
                "docker", "run", "--rm",
                "--name", container_name,
                "--network", "none",
                "-i", "python:3.12-slim",
                "python", "-I", "-",
            ],
            input=script,
            text=True,
            capture_output=True,
            timeout=timeout,
            check=False,
        )
    except subprocess.TimeoutExpired:
        subprocess.run(["docker", "rm", "-f", container_name], capture_output=True, check=False)
        return f"Error: code execution timed out after {timeout}s"
    except OSError as exc:
        return f"Error: failed to start container: {exc}"

    if completed.returncode != 0:
        stderr = completed.stderr.strip() or f"exit code {completed.returncode}"
        return f"Error: {stderr}"
    return completed.stdout.strip() or "(no output)"
```

代码中各组成部分的作用如下：

| 组成部分 | 代码标识 | 作用 |
| - | - | - |
| 容器执行函数 | `run_code()` | 启动无网络的一次性 Docker 容器运行模型生成的代码，限制 10 秒超时；成功时返回标准输出，超时或报错时清理容器并返回错误文本 |
| 请求函数 | `complete()` | 使用 OpenAI SDK 调用 `/v1/chat/completions` 接口 |
| 代码执行工具定义 | `RUN_CODE_TOOL` | 将 `run_code` 声明为函数工具，并在工具描述中向模型说明容器内可调用的函数签名、返回字段及只打印汇总结果的要求 |
| 容器内预置函数 | `SANDBOX_TOOLS` | 预置在容器内的只读查询函数（`list_order_ids()` 与 `get_order()`），供模型生成的代码直接调用 |

## 在工具调用循环中执行代码

将 `RUN_CODE_TOOL` 传入 `tools`，当模型返回 `run_code` 调用时，在容器中执行生成的 Python 代码并将输出结果回传给模型：

```python theme={null}
while True:
    response: dict[str, Any] = complete(
        messages=messages,
        tools=[RUN_CODE_TOOL],  # 向模型提供代码执行工具
    )
    assistant: Message = response["choices"][0]["message"]
    messages.append(assistant)  # 原样保留模型返回的完整 assistant 消息

    tool_calls: list[dict[str, Any]] = assistant.get("tool_calls") or []
    if not tool_calls:
        print(assistant.get("content"))
        break

    for call in tool_calls:
        name: str = call["function"]["name"]
        arguments: dict[str, Any] = json.loads(call["function"]["arguments"])
        if name == "run_code":
            # 在隔离容器中执行模型生成的代码，只拿到汇总后的标准输出
            output: str = run_code(arguments["code"])
        else:
            output = f"Error: unknown tool {name}"

        # 将代码输出（或报错信息）按 tool_call_id 追加回 messages，进入下一轮循环
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": output,
        })
```

## 常见问题

> [accordion] 实际业务里，生成的代码怎么访问我自己的数据或函数？
>
> 示例为演示方便，把 `ORDERS` 和查询函数直接写进 `SANDBOX_TOOLS`。实际接入时，生成的代码访问业务数据有两种常见做法：
>
> 1. **传入数据快照**：启动沙箱前，把当前步骤要筛选或汇总的数据序列化为 JSON，通过标准输入或只读文件传入沙箱。沙箱内的代码只做计算，不访问外部数据，适合数据量小、所需数据能提前确定的步骤。
> 2. **通过受控接口转发查询**：沙箱内只放轻量客户端桩函数（stub）；桩函数被调用时，经本地套接字或内部只读接口把请求转发给宿主服务，由宿主执行真实查询并返回结果。数据库密码和 API Key 只留在宿主侧，不进入沙箱，适合数据量大或需要边算边查的场景。

> [accordion] 执行环境一定要用 Docker 吗？
>
> 模型生成的代码需要在隔离环境中执行。在宿主进程里直接调用 `exec()` 执行，代码会以宿主权限运行，可以读写宿主文件、读取 `MOONSHOT_API_KEY` 等环境变量中的凭据；死循环或内存暴涨还会直接卡死主进程。
>
> 示例选用无网络的一次性 Docker 容器（`--rm --network none`），因为 Docker 在本地最容易跑通。生产环境可以换成启动更快的隔离环境，如 V8 isolate、WebAssembly 沙箱、Firecracker microVM 或云端代码沙箱服务。无论换成哪种，都要满足三个条件：生成的代码接触不到宿主凭据、单次执行有超时限制、执行报错时把错误文本作为普通 `tool` 结果回传给模型。
