Kimi SDK 使用指南用 Python 快速构建基于 Kimi API 的 Agent 工作流【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读Kimi SDK 是 kimi-cli 仓库中提供的轻量级 Python 封装它基于 monorepo 内的kosongLLM 抽象层为开发者提供了一条直达 Kimi APIMoonshot 平台的便捷通道你只需几行代码即可完成对话补全、流式输出、视频文件上传与工具调用并能进一步搭建完整的 Agent 循环。读完本文你将掌握kimi-sdk的安装方式、四个核心 APIKimi、generate、step、SimpleToolset的用法以及它们底层的实现原理与可复用的实战模式。Kimi SDK 是什么Kimi SDK包定义定位为 A lightweight Python SDK for the Kimi API当前版本 0.2.1要求 Python 3.12 及以上。它本身是一个极薄的封装层真正的 LLM 抽象逻辑消息结构、异步工具编排、可插拔的聊天 Provider全部位于同仓库的kosong包中kimi-sdk通过依赖kosong0.37.0并从中精选导出与 Kimi API 直接相关的能力。这一点在 包入口 中体现得很清楚kimi_sdk的__init__.py不做任何业务实现而是从kosong的chat_provider、message、tooling等模块批量导出符号并维护一份__all__白名单。你从kimi_sdk导入的每个名字其实现都可以在 kosong 源码 中找到对应定义。核心能力可归纳为三条generate发起一次补全把流式返回的 message parts 合并成完整的Message并附上可选的TokenUsage用量统计step在generate之上叠加工具分发Tool/Toolset/SimpleToolset返回带工具输出结果的StepResult消息与工具抽象Message、各类ContentPart文本、思考、图片、音频、视频、ToolCall等数据结构统一在这里定义。安装与项目初始化官方推荐使用uv作为包管理器uv 也承担本仓库的构建与开发工作流uv init --python 3.12 # or higher uv add kimi-sdk安装后即可在代码中导入from kimi_sdk import Kimi, Message, generate运行环境要求Python 3.12见 pyproject.toml 的requires-python字段依赖kosong0.37.0后者内部依赖openaiSDK 与httpx完成 HTTP 通信调用 API 前需准备 Moonshot 平台的 API Key可通过环境变量注入见下文环境变量一节。第一个示例简单的对话补全这是 README 中最基础也最核心的用法——创建KimiProvider构造历史消息然后调用generate获取回复import asyncio from kimi_sdk import Kimi, Message, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())关键参数说明参数说明base_urlKimi API 的端点前缀默认https://api.moonshot.ai/v1api_keyAPI Key不传时自动回落到KIMI_API_KEY环境变量model模型名如kimi-k2-turbo-previewchat_provider传给generate的 Provider 实例即上面的kimisystem_prompt系统提示词tools可用的工具列表这里为空history消息历史Message(roleuser, content...)的列表generate返回GenerateResult其中message是模型生成的完整消息可直接print查看文本usage是TokenUsage用量对象。从 GenerateResult 定义 可以看到它还携带id消息 ID与trace_id响应的x-trace-id请求头便于排查问题。流式输出逐块接收消息generate默认走流式通道你可以通过on_message_part回调实时拿到每一个到达的 message part从而实现打字机式的输出效果import asyncio from kimi_sdk import Kimi, Message, StreamedMessagePart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] def output(message_part: StreamedMessagePart) - None: print(message_part) result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, on_message_partoutput, ) print(result.message) print(result.usage) asyncio.run(main())流式 part 如何被合并在 generate 实现 中generate先调用chat_provider.generate(...)拿到一个异步流然后逐块迭代每个 part 先通过on_message_part回调以深拷贝形式暴露给调用方避免外部修改污染内部状态如果前一个 part 尚未完成会尝试用pending_part.merge_in_place(part)把新的分片合并进去例如被切分的文本增量合并不了才推入消息缓冲区流结束时把所有待处理的 part 写入最终Message并做异常兜底如果响应内容为空或只有ThinkPart思考内容却没有可见文本和工具调用则抛出APIEmptyResponseError——后者通常意味着流被中断或输出 token 预算在推理阶段耗尽。因此result.message始终是合并完整、可直接使用的消息而on_message_part只用于实时展示。上传视频把本地文件变成消息内容Kimi SDK 支持把视频作为多模态输入送入对话。核心是kimi.files.upload_video(...)它走 KimiFiles 实现import asyncio from pathlib import Path from kimi_sdk import Kimi, Message, TextPart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) video_path Path(demo.mp4) video_part await kimi.files.upload_video( datavideo_path.read_bytes(), mime_typevideo/mp4, ) history [ Message( roleuser, content[ TextPart(textPlease describe this video.), video_part, ], ), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())upload_video 的底层行为mime_type必须以video/开头否则抛出ChatProviderErrorSDK 通过底层 OpenAI 兼容客户端向/files接口发起multipart/form-data上传purpose固定为video文件名由mimetypes根据 MIME 类型推断上传成功后返回一个VideoURLPart其内部 URL 形如ms://{file_id}可直接作为Message.content的一个元素参与后续补全消息内容因此支持多种ContentPart组合除了TextPart与VideoURLPart包入口 还导出了ThinkPart、ImageURLPart、AudioURLPart等可用于构建富媒体对话。工具调用基于 step 的 Agent 单步执行当模型需要调用外部函数时使用step而不是generate。step在generate之上自动完成工具调用的分发一个经典的整数加法工具示例如下import asyncio from pydantic import BaseModel from kimi_sdk import CallableTool2, Kimi, Message, SimpleToolset, StepResult, ToolOk, ToolReturnValue, step class AddToolParams(BaseModel): a: int b: int class AddTool(CallableTool2[AddToolParams]): name: str add description: str Add two integers. params: type[AddToolParams] AddToolParams async def __call__(self, params: AddToolParams) - ToolReturnValue: return ToolOk(outputstr(params.a params.b)) async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() toolset AddTool() history [ Message(roleuser, contentPlease add 2 and 3 with the add tool.), ] result: StepResult await step( chat_providerkimi, system_promptYou are a precise math tutor., toolsettoolset, historyhistory, ) print(result.message) print(await result.tool_results()) asyncio.run(main())定义一个工具的三要素以CallableTool2[T]为基类、T为 Pydantic 参数模型name工具名会作为 function calling 的name发给模型description工具说明帮助模型决定何时调用params参数 schemaPydantic 模型类__call__真正的执行逻辑返回ToolReturnValue。返回ToolOk(output...)表示成功另有ToolError表示失败两者定义在 tooling 模块 中。SimpleToolset支持语法批量注册工具toolset.tools会在请求时转换为 OpenAI 兼容的工具参数格式。step 与 StepResult 的行为契约从 step 源码 可以确认以下细节step每调用一次只让模型生成一轮工具调用由toolset.handle(tool_call)立即分发执行执行结果包装在ToolResultFuture中可通过await result.tool_results()统一取回StepResult暴露id、message、usage、tool_calls与tool_results()其中tool_calls列出本轮模型请求的全部工具调用step不会修改传入的 history——是否把本轮消息与工具结果追加回历史由调用方决定这让 Agent 循环的状态管理完全透明可控若生成过程中出现ChatProviderError或任务取消step会取消所有未完成的工具 future避免后台任务悬挂支持的异常类型包括APIConnectionError、APITimeoutError、APIStatusError4xx/5xx、APIEmptyResponseError及统一的ChatProviderError基类。实战完整的 Agent 循环将step与手动维护的history组合即可写出一个可交互的 Agent 主循环该示例来自 kimi_sdk 包入口文档 并在此展开import asyncio from kimi_sdk import Kimi, Message, SimpleToolset, StepResult, ToolResult, step def tool_result_to_message(result: ToolResult) - Message: return Message( roletool, tool_call_idresult.tool_call_id, contentresult.return_value.output, ) async def agent_loop() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() # toolset YourTool() # 注册你的工具 history: list[Message] [] system_prompt You are a helpful assistant. while True: user_input input(You: ).strip() if not user_input: continue if user_input.lower() in {exit, quit}: break history.append(Message(roleuser, contentuser_input)) while True: result: StepResult await step( chat_providerkimi, system_promptsystem_prompt, toolsettoolset, historyhistory, ) history.append(result.message) tool_results await result.tool_results() for tool_result in tool_results: history.append(tool_result_to_message(tool_result)) if text : result.message.extract_text(): print(Assistant:, text) if not result.tool_calls: break asyncio.run(agent_loop())这个循环揭示了 Agent 的标准运转模式读取用户输入追加为user消息内层循环反复执行step每轮把模型消息写入历史、取回工具结果并转成roletool的消息回填历史Message.extract_text()用于抽取当前轮次的可见文本并打印当result.tool_calls为空模型不再调用工具时退出内层循环回到等待用户输入。roletool的消息通过tool_call_id与模型发出的ToolCall一一对应这正是 OpenAI 兼容 function calling 协议所要求的闭环格式。环境变量Kimi SDK 支持两个环境变量其读取逻辑在 Kimi 构造器 中环境变量作用默认值KIMI_API_KEYKimi API 的 API Key无未设置且未传api_key参数时抛出ChatProviderErrorKIMI_BASE_URL覆盖 API 基础地址https://api.moonshot.ai/v1注意优先级显式传入的构造参数优先于环境变量。例如Kimi(model..., api_keysk-xxx)会忽略KIMI_API_KEY而Kimi(model...)则会读取KIMI_API_KEY。深入Kimi Provider 的高级能力除了 README 示例Kimi 类实现 还提供了不少值得在生产中使用的进阶特性生成参数GenerationKwargs支持max_completion_tokens旧别名max_tokens会自动归一化、temperature、top_p、n、presence_penalty、frequency_penalty、stop、prompt_cache_key、reasoning_effort与extra_body等通过with_generation_kwargs以不可变副本方式应用kimi kimi.with_generation_kwargs(temperature0, max_completion_tokens1000)思考模式与 preserved thinkingwith_thinking(effort)接受ThinkingEffort如off底层通过extra_body.thinking.type控制是否启用思考Moonshot 特有的thinking.keep如all用于保留推理内容由with_extra_body按字段合并不会覆盖已设置的thinking.type。内置函数与 schema 兼容工具名以$开头的工具会被映射为 Kimi 内置函数builtin_function无需提供 description 和 parameters自动对工具参数 schema 做ensure_property_types归一化修复部分 MCP 服务器产出的缺省type的嵌套属性导致的 400 错误。用量与可观测性TokenUsage区分input_other非缓存输入、output输出与input_cache_read缓存命中输入KimiStreamedMessage会兼容处理 Moonshot 与 OpenAI 两种 usage 字段格式。StepResult.trace_id与generate的on_trace_id回调可拿到响应的x-trace-id方便链路追踪。测试验证仓库为 SDK 提供了冒烟测试 tests/test_smoke.py使用httpx.MockTransport拦截请求并返回模拟的 chat completion 响应验证了generate会向/v1/chat/completions发起请求非流式模式下streamFalseresult.message.extract_text()能正确取出Helloresult.usage.input_other 10、result.usage.output 5的用量解析逻辑正确。这个测试模式非常实用通过注入自定义http_clienthttpx.AsyncClient你可以在不真正调用 Kimi API 的情况下对自家 Agent 逻辑做单元测试。版本演进从 CHANGELOG 可以看到 SDK 的发展脉络0.1.0 首次发布0.2.0 导出KimiFiles以支持视频文件上传0.2.1 放宽kosong依赖上限以兼容 0.40.x。如果你在本仓库中开发可以留意kosong的版本约束与kimi-sdk的导出面随版本逐步扩充。小结Kimi SDK 用极薄的 API 面把连接 Kimi API 构建 Agent 工作流这件事做到了开箱即用generate负责对话与流式合并step负责工具分发SimpleToolsetCallableTool2负责工具定义Message与ContentPart负责统一的多模态消息模型。结合底层kosong源码阅读你既能快速上手也能理解流式合并、工具 future 编排、异常兜底等内部机制从而在自己的 Python 项目中搭建稳定、可测试的 Agent 应用。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考