From 6361f8216443f569dae4bcdf75bf49f192d0a817 Mon Sep 17 00:00:00 2001 From: Kaiyi Date: Wed, 21 Jan 2026 21:08:18 +0800 Subject: [PATCH 1/3] docs: Add module level docstring for each module of the Kimi Agent SDK --- python/src/kimi_agent_sdk/__init__.py | 62 ++++++++++++++++++++++++ python/src/kimi_agent_sdk/_aggregator.py | 27 +++++++++++ python/src/kimi_agent_sdk/_approval.py | 26 ++++++++++ python/src/kimi_agent_sdk/_exception.py | 14 ++++++ python/src/kimi_agent_sdk/_prompt.py | 59 ++++++++++++++++++++++ python/src/kimi_agent_sdk/_session.py | 38 +++++++++++++++ 6 files changed, 226 insertions(+) diff --git a/python/src/kimi_agent_sdk/__init__.py b/python/src/kimi_agent_sdk/__init__.py index 0fd3ec9..6f63c78 100644 --- a/python/src/kimi_agent_sdk/__init__.py +++ b/python/src/kimi_agent_sdk/__init__.py @@ -1,3 +1,65 @@ +""" +Kimi Agent SDK is a Python SDK for building AI agents powered by Kimi. +It provides both high-level and low-level APIs for seamless agent integration, stateful sessions, +and tool orchestration in modern AI applications. + +Key features: + +- `kimi_agent_sdk.prompt` provides a high-level async generator API that sends prompts to Kimi + and yields aggregated Message objects, handling approval requests automatically or via custom + handlers. +- `kimi_agent_sdk.Session` offers low-level control with Wire message access, manual approval + handling, session persistence, and context management for long-running agent interactions. +- Message structures, approval types, and exceptions are re-exported from kosong and kimi_cli + for convenient access. + +Example (high-level API): + +```python +import asyncio + +from kimi_agent_sdk import prompt + + +async def main() -> None: + async for message in prompt( + "What is the capital of France?", + model="kimi", + yolo=True, + ): + print(message.extract_text()) + + +asyncio.run(main()) +``` + +Example (low-level API with Session): + +```python +import asyncio + +from kaos.path import KaosPath + +from kimi_agent_sdk import ApprovalRequest, Session + + +async def main() -> None: + async with await Session.create( + work_dir=KaosPath.cwd(), + model="kimi", + yolo=False, + ) as session: + async for wire_msg in session.prompt("What is the capital of France?"): + if isinstance(wire_msg, ApprovalRequest): + wire_msg.resolve("approve") + else: + print(wire_msg) + + +asyncio.run(main()) +``` +""" + from __future__ import annotations from fastmcp.mcp_config import MCPConfig diff --git a/python/src/kimi_agent_sdk/_aggregator.py b/python/src/kimi_agent_sdk/_aggregator.py index 1d342e1..65eaf8d 100644 --- a/python/src/kimi_agent_sdk/_aggregator.py +++ b/python/src/kimi_agent_sdk/_aggregator.py @@ -1,3 +1,30 @@ +""" +Wire message aggregation for Kimi Agent SDK. + +This module provides the MessageAggregator class that transforms streaming Wire messages +(low-level protocol messages) into aggregated Message objects (high-level content structures). +It supports two output modes: full step-by-step messages with tool calls/results, or final +message text only. + +Key classes: + +- `MessageAggregator` buffers and merges WireMessage events (ContentPart, ToolCall, ToolResult) + and flushes them as complete Message objects at step boundaries. + +Example: + +```python +from kimi_agent_sdk._aggregator import MessageAggregator + +aggregator = MessageAggregator(final_message_only=False) +for wire_msg in wire_stream: + for message in aggregator.feed(wire_msg): + print(message) +for message in aggregator.flush(): + print(message) +``` +""" + from __future__ import annotations from dataclasses import dataclass diff --git a/python/src/kimi_agent_sdk/_approval.py b/python/src/kimi_agent_sdk/_approval.py index 2f0c9ee..3bf26ed 100644 --- a/python/src/kimi_agent_sdk/_approval.py +++ b/python/src/kimi_agent_sdk/_approval.py @@ -1,3 +1,29 @@ +""" +Approval handling types for Kimi Agent SDK. + +This module defines the ApprovalHandlerFn type for custom approval handling in agent sessions. +Approval handlers allow you to programmatically approve or reject tool execution requests from +the agent, providing fine-grained control over what actions the agent can perform. + +Key types: + +- `ApprovalHandlerFn` is a callback function type that receives ApprovalRequest objects and + resolves them with "approve", "approve_for_session", or "reject". + +Example: + +```python +from kimi_agent_sdk import ApprovalRequest + + +def my_handler(request: ApprovalRequest) -> None: + if request.sender == "bash": + request.resolve("approve") + else: + request.resolve("reject") +``` +""" + from __future__ import annotations from collections.abc import Awaitable, Callable diff --git a/python/src/kimi_agent_sdk/_exception.py b/python/src/kimi_agent_sdk/_exception.py index 919f291..d5a5d36 100644 --- a/python/src/kimi_agent_sdk/_exception.py +++ b/python/src/kimi_agent_sdk/_exception.py @@ -1,3 +1,17 @@ +""" +Custom exceptions for Kimi Agent SDK. + +This module defines SDK-specific exceptions for validation and state management errors. +All exceptions inherit from KimiCLIException for consistent error handling across the SDK. + +Key exceptions: + +- `PromptValidationError` is raised when prompt configuration is invalid (e.g., neither yolo + nor approval_handler_fn is provided). +- `SessionStateError` is raised when session operations are performed in invalid states (e.g., + prompting while already running or after closing). +""" + from __future__ import annotations from kimi_cli.exception import KimiCLIException diff --git a/python/src/kimi_agent_sdk/_prompt.py b/python/src/kimi_agent_sdk/_prompt.py index 2ccbfa6..03f38e1 100644 --- a/python/src/kimi_agent_sdk/_prompt.py +++ b/python/src/kimi_agent_sdk/_prompt.py @@ -1,3 +1,62 @@ +""" +High-level prompt API for Kimi Agent SDK. + +This module provides the prompt function, the highest-level API for sending prompts to Kimi +and receiving aggregated Message responses. It handles session lifecycle, approval requests, +and message aggregation automatically. + +Key functions: + +- `prompt` is an async generator that creates a session, sends a prompt, handles approvals via + yolo mode or custom handler, and yields aggregated Message objects similar to + `kimi --print --output stream-json`. + +Example: + +```python +import asyncio + +from kimi_agent_sdk import prompt + + +async def main() -> None: + async for message in prompt( + "What is 2 + 3?", + model="kimi", + yolo=True, + ): + print(message.extract_text()) + + +asyncio.run(main()) +``` + +Example (with custom approval handler): + +```python +import asyncio + +from kimi_agent_sdk import ApprovalRequest, prompt + + +def my_approval_handler(request: ApprovalRequest) -> None: + print(f"Approval requested: {request.description}") + request.resolve("approve") + + +async def main() -> None: + async for message in prompt( + "Create a file named test.txt", + model="kimi", + approval_handler_fn=my_approval_handler, + ): + print(message.extract_text()) + + +asyncio.run(main()) +``` +""" + from __future__ import annotations import inspect diff --git a/python/src/kimi_agent_sdk/_session.py b/python/src/kimi_agent_sdk/_session.py index 10ad26d..500983c 100644 --- a/python/src/kimi_agent_sdk/_session.py +++ b/python/src/kimi_agent_sdk/_session.py @@ -1,3 +1,41 @@ +""" +Session management for Kimi Agent SDK. + +This module provides the Session class for low-level agent control with Wire message access, +manual approval handling, and session persistence. Use Session when you need full control over +agent execution flow, custom approval logic, or resumable sessions across multiple prompts. + +Key classes: + +- `Session` wraps KimiCLI to provide stateful agent sessions with async context manager support, + cancellation, and resource cleanup. + +Example: + +```python +import asyncio + +from kaos.path import KaosPath + +from kimi_agent_sdk import ApprovalRequest, Session + + +async def main() -> None: + async with await Session.create( + work_dir=KaosPath.cwd(), + model="kimi", + ) as session: + async for wire_msg in session.prompt("Hello!"): + if isinstance(wire_msg, ApprovalRequest): + wire_msg.resolve("approve") + else: + print(wire_msg) + + +asyncio.run(main()) +``` +""" + from __future__ import annotations import asyncio From 177c883a884a8428536083d8443e6de392e27f98 Mon Sep 17 00:00:00 2001 From: Kaiyi Date: Wed, 21 Jan 2026 21:17:44 +0800 Subject: [PATCH 2/3] Revert "docs: Add module level docstring for each module of the Kimi Agent SDK" This reverts commit 6361f8216443f569dae4bcdf75bf49f192d0a817. --- python/src/kimi_agent_sdk/__init__.py | 62 ------------------------ python/src/kimi_agent_sdk/_aggregator.py | 27 ----------- python/src/kimi_agent_sdk/_approval.py | 26 ---------- python/src/kimi_agent_sdk/_exception.py | 14 ------ python/src/kimi_agent_sdk/_prompt.py | 59 ---------------------- python/src/kimi_agent_sdk/_session.py | 38 --------------- 6 files changed, 226 deletions(-) diff --git a/python/src/kimi_agent_sdk/__init__.py b/python/src/kimi_agent_sdk/__init__.py index 6f63c78..0fd3ec9 100644 --- a/python/src/kimi_agent_sdk/__init__.py +++ b/python/src/kimi_agent_sdk/__init__.py @@ -1,65 +1,3 @@ -""" -Kimi Agent SDK is a Python SDK for building AI agents powered by Kimi. -It provides both high-level and low-level APIs for seamless agent integration, stateful sessions, -and tool orchestration in modern AI applications. - -Key features: - -- `kimi_agent_sdk.prompt` provides a high-level async generator API that sends prompts to Kimi - and yields aggregated Message objects, handling approval requests automatically or via custom - handlers. -- `kimi_agent_sdk.Session` offers low-level control with Wire message access, manual approval - handling, session persistence, and context management for long-running agent interactions. -- Message structures, approval types, and exceptions are re-exported from kosong and kimi_cli - for convenient access. - -Example (high-level API): - -```python -import asyncio - -from kimi_agent_sdk import prompt - - -async def main() -> None: - async for message in prompt( - "What is the capital of France?", - model="kimi", - yolo=True, - ): - print(message.extract_text()) - - -asyncio.run(main()) -``` - -Example (low-level API with Session): - -```python -import asyncio - -from kaos.path import KaosPath - -from kimi_agent_sdk import ApprovalRequest, Session - - -async def main() -> None: - async with await Session.create( - work_dir=KaosPath.cwd(), - model="kimi", - yolo=False, - ) as session: - async for wire_msg in session.prompt("What is the capital of France?"): - if isinstance(wire_msg, ApprovalRequest): - wire_msg.resolve("approve") - else: - print(wire_msg) - - -asyncio.run(main()) -``` -""" - from __future__ import annotations from fastmcp.mcp_config import MCPConfig diff --git a/python/src/kimi_agent_sdk/_aggregator.py b/python/src/kimi_agent_sdk/_aggregator.py index 65eaf8d..1d342e1 100644 --- a/python/src/kimi_agent_sdk/_aggregator.py +++ b/python/src/kimi_agent_sdk/_aggregator.py @@ -1,30 +1,3 @@ -""" -Wire message aggregation for Kimi Agent SDK. - -This module provides the MessageAggregator class that transforms streaming Wire messages -(low-level protocol messages) into aggregated Message objects (high-level content structures). -It supports two output modes: full step-by-step messages with tool calls/results, or final -message text only. - -Key classes: - -- `MessageAggregator` buffers and merges WireMessage events (ContentPart, ToolCall, ToolResult) - and flushes them as complete Message objects at step boundaries. - -Example: - -```python -from kimi_agent_sdk._aggregator import MessageAggregator - -aggregator = MessageAggregator(final_message_only=False) -for wire_msg in wire_stream: - for message in aggregator.feed(wire_msg): - print(message) -for message in aggregator.flush(): - print(message) -``` -""" - from __future__ import annotations from dataclasses import dataclass diff --git a/python/src/kimi_agent_sdk/_approval.py b/python/src/kimi_agent_sdk/_approval.py index 3bf26ed..2f0c9ee 100644 --- a/python/src/kimi_agent_sdk/_approval.py +++ b/python/src/kimi_agent_sdk/_approval.py @@ -1,29 +1,3 @@ -""" -Approval handling types for Kimi Agent SDK. - -This module defines the ApprovalHandlerFn type for custom approval handling in agent sessions. -Approval handlers allow you to programmatically approve or reject tool execution requests from -the agent, providing fine-grained control over what actions the agent can perform. - -Key types: - -- `ApprovalHandlerFn` is a callback function type that receives ApprovalRequest objects and - resolves them with "approve", "approve_for_session", or "reject". - -Example: - -```python -from kimi_agent_sdk import ApprovalRequest - - -def my_handler(request: ApprovalRequest) -> None: - if request.sender == "bash": - request.resolve("approve") - else: - request.resolve("reject") -``` -""" - from __future__ import annotations from collections.abc import Awaitable, Callable diff --git a/python/src/kimi_agent_sdk/_exception.py b/python/src/kimi_agent_sdk/_exception.py index d5a5d36..919f291 100644 --- a/python/src/kimi_agent_sdk/_exception.py +++ b/python/src/kimi_agent_sdk/_exception.py @@ -1,17 +1,3 @@ -""" -Custom exceptions for Kimi Agent SDK. - -This module defines SDK-specific exceptions for validation and state management errors. -All exceptions inherit from KimiCLIException for consistent error handling across the SDK. - -Key exceptions: - -- `PromptValidationError` is raised when prompt configuration is invalid (e.g., neither yolo - nor approval_handler_fn is provided). -- `SessionStateError` is raised when session operations are performed in invalid states (e.g., - prompting while already running or after closing). -""" - from __future__ import annotations from kimi_cli.exception import KimiCLIException diff --git a/python/src/kimi_agent_sdk/_prompt.py b/python/src/kimi_agent_sdk/_prompt.py index 03f38e1..2ccbfa6 100644 --- a/python/src/kimi_agent_sdk/_prompt.py +++ b/python/src/kimi_agent_sdk/_prompt.py @@ -1,62 +1,3 @@ -""" -High-level prompt API for Kimi Agent SDK. - -This module provides the prompt function, the highest-level API for sending prompts to Kimi -and receiving aggregated Message responses. It handles session lifecycle, approval requests, -and message aggregation automatically. - -Key functions: - -- `prompt` is an async generator that creates a session, sends a prompt, handles approvals via - yolo mode or custom handler, and yields aggregated Message objects similar to - `kimi --print --output stream-json`. - -Example: - -```python -import asyncio - -from kimi_agent_sdk import prompt - - -async def main() -> None: - async for message in prompt( - "What is 2 + 3?", - model="kimi", - yolo=True, - ): - print(message.extract_text()) - - -asyncio.run(main()) -``` - -Example (with custom approval handler): - -```python -import asyncio - -from kimi_agent_sdk import ApprovalRequest, prompt - - -def my_approval_handler(request: ApprovalRequest) -> None: - print(f"Approval requested: {request.description}") - request.resolve("approve") - - -async def main() -> None: - async for message in prompt( - "Create a file named test.txt", - model="kimi", - approval_handler_fn=my_approval_handler, - ): - print(message.extract_text()) - - -asyncio.run(main()) -``` -""" - from __future__ import annotations import inspect diff --git a/python/src/kimi_agent_sdk/_session.py b/python/src/kimi_agent_sdk/_session.py index 500983c..10ad26d 100644 --- a/python/src/kimi_agent_sdk/_session.py +++ b/python/src/kimi_agent_sdk/_session.py @@ -1,41 +1,3 @@ -""" -Session management for Kimi Agent SDK. - -This module provides the Session class for low-level agent control with Wire message access, -manual approval handling, and session persistence. Use Session when you need full control over -agent execution flow, custom approval logic, or resumable sessions across multiple prompts. - -Key classes: - -- `Session` wraps KimiCLI to provide stateful agent sessions with async context manager support, - cancellation, and resource cleanup. - -Example: - -```python -import asyncio - -from kaos.path import KaosPath - -from kimi_agent_sdk import ApprovalRequest, Session - - -async def main() -> None: - async with await Session.create( - work_dir=KaosPath.cwd(), - model="kimi", - ) as session: - async for wire_msg in session.prompt("Hello!"): - if isinstance(wire_msg, ApprovalRequest): - wire_msg.resolve("approve") - else: - print(wire_msg) - - -asyncio.run(main()) -``` -""" - from __future__ import annotations import asyncio From f13c0792f3c984a3c061a13978bbcc60387e0fb3 Mon Sep 17 00:00:00 2001 From: Kaiyi Date: Wed, 21 Jan 2026 21:19:05 +0800 Subject: [PATCH 3/3] docs: Add module level docstring for Kimi Agent SDK python --- python/src/kimi_agent_sdk/__init__.py | 62 +++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/python/src/kimi_agent_sdk/__init__.py b/python/src/kimi_agent_sdk/__init__.py index 0fd3ec9..6f63c78 100644 --- a/python/src/kimi_agent_sdk/__init__.py +++ b/python/src/kimi_agent_sdk/__init__.py @@ -1,3 +1,65 @@ +""" +Kimi Agent SDK is a Python SDK for building AI agents powered by Kimi. +It provides both high-level and low-level APIs for seamless agent integration, stateful sessions, +and tool orchestration in modern AI applications. + +Key features: + +- `kimi_agent_sdk.prompt` provides a high-level async generator API that sends prompts to Kimi + and yields aggregated Message objects, handling approval requests automatically or via custom + handlers. +- `kimi_agent_sdk.Session` offers low-level control with Wire message access, manual approval + handling, session persistence, and context management for long-running agent interactions. +- Message structures, approval types, and exceptions are re-exported from kosong and kimi_cli + for convenient access. + +Example (high-level API): + +```python +import asyncio + +from kimi_agent_sdk import prompt + + +async def main() -> None: + async for message in prompt( + "What is the capital of France?", + model="kimi", + yolo=True, + ): + print(message.extract_text()) + + +asyncio.run(main()) +``` + +Example (low-level API with Session): + +```python +import asyncio + +from kaos.path import KaosPath + +from kimi_agent_sdk import ApprovalRequest, Session + + +async def main() -> None: + async with await Session.create( + work_dir=KaosPath.cwd(), + model="kimi", + yolo=False, + ) as session: + async for wire_msg in session.prompt("What is the capital of France?"): + if isinstance(wire_msg, ApprovalRequest): + wire_msg.resolve("approve") + else: + print(wire_msg) + + +asyncio.run(main()) +``` +""" + from __future__ import annotations from fastmcp.mcp_config import MCPConfig