Install & Compatibility
Where this runs
tested against v0.56.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
110MB installed
● package 110MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate
✓ from kosong import generate
✗ import kosong
ChatProvider
✓ from kosong import ChatProvider
Message
✓ from kosong import Message
This quickstart demonstrates how to use `kosong.step` with a `Kimi` chat provider and a custom tool (`AddTool`). It shows the setup of a `SimpleToolset`, message history, and how to execute an agent step, including retrieving asynchronous tool results. Remember to set your `KIMI_API_KEY` environment variable.
import asyncio
import os
from pydantic import BaseModel
import kosong
from kosong import StepResult
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message
from kosong.tooling import CallableTool2, ToolOk, ToolReturnValue
from kosong.tooling.simple import SimpleToolset
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(output=str(params.a + params.b))
async def main() -> None:
# Initialize a Kimi chat provider using environment variables for API key
kimi = Kimi(
base_url=os.environ.get("KIMI_BASE_URL", "https://api.moonshot.ai/v1"),
api_key=os.environ.get("KIMI_API_KEY", "your_kimi_api_key_here"), # Replace with your Kimi API key or set KIMI_API_KEY env var
model="kimi-k2-turbo-preview",
)
# Create a toolset and add the AddTool
toolset = SimpleToolset()
toolset += AddTool()
# Define message history
history = [
Message(role="user", content="Please add 2 and 3 with the add tool."),
]
# Run an agent step
print("Running agent step...")
result: StepResult = await kosong.step(
chat_provider=kimi,
system_prompt="You are a precise math tutor.",
toolset=toolset,
history=history,
)
# Print the generated message and awaited tool results
print(f"Generated message: {result.message}")
print(f"Tool results: {await result.tool_results()}")
if __name__ == "__main__":
asyncio.run(main())
kosong --version
Debug
Known issues
breakingThe `kosong` project's development has moved to a monorepo structure. The original `MoonshotAI/kosong` GitHub repository is archived, and ongoing development can be found under `MoonshotAI/kimi-cli/tree/main/packages/kosong`. While PyPI distribution remains `kosong`, this change affects direct repository interaction or contribution.fixRefer to the `kimi-cli` monorepo for the latest source code, issues, and contribution guidelines: `https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kosong`.
affects: All versions after the repository move (approx. last 4 months as of current date)
gotchaKosong requires Python 3.12 or higher. Attempting to install or run with older Python versions will result in an error.fixEnsure your development environment uses Python 3.12 or a newer compatible version.
affects: All versions
gotchaWhen using `kosong.step` with tools, the tool outputs are typically handled asynchronously. You must `await result.tool_results()` to fetch the collected tool outputs from a `StepResult`. Failing to `await` this call will result in an unresolved coroutine object instead of the actual tool outputs.fixAlways use `await result.tool_results()` to correctly retrieve tool execution results after a `kosong.step` call that involves tools.
affects: All versions
gotchaDefining custom tools with `CallableTool2` (and similar tool abstractions) relies on `pydantic.BaseModel` for parameter serialization and validation. Ensure `pydantic` is installed and parameter models correctly inherit from `BaseModel`.fixInstall `pydantic` (`pip install pydantic`) and define tool parameters by subclassing `pydantic.BaseModel`.
affects: All versions
Upgrade
Version history
0.56.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
pydanticrequiredRequired for defining tool parameters using `BaseModel` for `CallableTool2`.