Что такое Kosong

Kosong — это библиотека на Python от Moonshot AI, представляющая собой слой абстракции для LLM в агентных приложениях. Она размещается между бизнес-логикой агента и поставщиками моделей, унифицирует структуру сообщений, семантику потоковой передачи и асинхронную оркестрацию вызовов инструментов, чтобы код агента не привязывался к конкретному API. Kosong также служит базой для Kimi CLI.

Основные концепции и API

Публичный API у Kosong предельно небольшой. На верхнем уровне обычно используются kosong.generate, kosong.step и типы результатов GenerateResult и StepResult. Вспомогательные модули включают kosong.chat_provider, kosong.message, kosong.tooling и kosong.tooling.simple.

Эти модули скрывают за единым интерфейсом специфичные для провайдеров форматы стрима, учет токенов и вызовы инструментов, так что код агента остается стабильным даже при смене моделей или провайдеров.

ChatProvider и модель сообщений

Ключевой точкой интеграции является абстракция ChatProvider. В репозитории приведена реализация провайдера Kimi в kosong.chat_provider.kimi. Экземпляр Kimi создается с base_url, api_key и именем модели вроде kimi-k2-turbo-preview. Этот провайдер передается в kosong.generate или kosong.step вместе с системным промптом, набором инструментов и историей сообщений.

Сообщения представлены классом Message из kosong.message. Message создается с ролью типа user и содержимым. Содержимое может быть строкой или списком частей, что позволяет поддерживать более сложные мультимодальные полезные нагрузки. Во время стриминга провайдеры испускают StreamedMessagePart через kosong.chat_provider, а библиотека собирает эти части в итоговое сообщение.

Также Kosong предоставляет структуру TokenUsage для независимого учета токенов, которую можно прикреплять к объектам результатов для логирования и мониторинга.

Инструменты и SimpleToolset

Большинству стеков агентов требуются инструменты: поиск, исполнение кода, работа с базой данных и т. п. Kosong моделирует инструменты в модуле tooling. Примеры показывают определение инструмента через наследование CallableTool2 с Pydantic моделью параметров. Инструменты возвращают ToolReturnType, например ToolOk при успешном выполнении.

Инструменты регистрируются в SimpleToolset из kosong.tooling.simple. В примерах набор инструментов дополняют с помощью оператора +=. Именно toolset решает, как сопоставлять вызовы инструментов, сгенерированные моделью, и маршрутизировать их к правильным асинхронным функциям.

generate для простых завершений чата

Функция kosong.generate подходит для одношаговых запросов чата. Необходимо передать chat_provider, system_prompt, список tools (может быть пуст) и историю Message. Kosong поддерживает стриминг через колбэк on_message_part. По завершении generate возвращает GenerateResult с объединенным сообщением ассистента и опциональной структурой TokenUsage, что позволяет показывать инкрементный вывод и работать с чистым итоговым объектом сообщения.

step для агентов с вызовами инструментов

Для сценариев, где модель вызывает инструменты, используется kosong.step. Вызов step получает ChatProvider, SimpleToolset с доступными инструментами, системный промпт и историю. step возвращает StepResult; в примере демонстрируют вывод result.message и ожидание result.tool_results() для сбора всех результатов инструментов.

Kosong берет на себя оркестрацию вызовов инструментов, в том числе преобразование аргументов в Pydantic-модели и конвертацию в ToolReturnType, освобождая разработчиков агентов от написания собственного цикла диспетчеризации для каждого провайдера.

Демонстрация и интеграция с Kimi CLI

В репозитории Kosong есть встроенный демонстрационный агент, который можно запускать локально. В README описаны переменные окружения KIMI_BASE_URL и KIMI_API_KEY и команда запуска через python -m kosong kimi --with-bash под uvicorn. Демо использует Kimi как провайдера чата и может открывать терминальный агент с возможностью вызова инструментов, включая shell-команды при включенной опции with bash.

Зачем это важно

Фокус на ChatProvider, Message и Toolset дает Kosong компактную и практичную инфраструктуру для долгоживущих агентных систем, которые должны менять модели и провайдеров без переписывания логики оркестрации. Это прагматичный шаг от Moonshot AI, который обеспечивает основу для Kimi CLI и других стеков, стремящихся к гибкости и простоте расширения.