Kimi Agent SDK

The Kimi Code runtime is structured around three hierarchical concepts:

• Session: The top-level container representing a running Kimi Code process. It maintains the configuration, available tools, and the entire conversation state.
• Turn: A single interaction initiated by calling Session.prompt(...). A turn encompasses the full round-trip from the user's input to the complete streamed response from the agent.
• Step: The granular units of work within a single Turn. As an agent reasons, calls tools, or produces output, it moves through steps. You can identify step boundaries in the Wire stream via StepBegin and StepInterrupted events.

Important Constraints:

• Sequentiality: You must fully consume a turn (iterate through the entire stream) or explicitly cancel() it before you can start a new turn on the same session. Starting a new prompt while one is active raises a SessionStateError.
• Approvals: If the agent requests permission via an ApprovalRequest, you must resolve it. An unresolved request will block the turn indefinitely.

# A Turn is one call to prompt()
async for msg in session.prompt("Hello"):
    # This loop processes the Turn
    pass

The go/wire/jsonrpc2 package implements a custom streaming extension to multiplex stream frames over a single JSON-RPC connection using the id field. This extension is not part of the official JSON-RPC 2.0 spec.

Stream States (stream field)

Constants defined in go/wire/jsonrpc2/codec.go:

• StreamDisable (0): Standard request/response; no stream expected.
• StreamOpen (1): Declares that the current id is authorized for subsequent stream frames. This is set on the base request or response.
• StreamSync (2): A data frame containing payload in the data field.
• StreamClose (3): An EOF frame indicating the end of the stream.

Wire Semantics

1. Stream-enabled base message: A message where stream == StreamOpen. It functions as a normal request/response but signals that the id can handle multiplexed frames.
2. Stream frames: Messages where stream > StreamOpen. These are treated as frames rather than requests/responses:
   • stream == StreamSync: Contains data (json.RawMessage).
   • stream == StreamClose: Signals end-of-stream; data is typically omitted.

Critical Requirement: Globally Unique IDs

If a connection is bi-directional (the Codec acts as both client and server), both sides must ensure that id values are globally unique across both directions to prevent stream frames from being routed to the wrong receiver.

When the agent attempts an action that requires permission (like running a shell command), it emits an ApprovalRequest. You must resolve these requests to allow the turn to proceed.

ApprovalRequest Properties:

• id: Unique identifier for the request.
• action: The type of action (e.g., "run shell command").
• description: A human-readable explanation of what the agent wants to do.

Resolution Options: Call req.resolve(choice) with one of the following strings:

• "approve": Approves the current request.
• "approve_for_session": Approves the current request and all subsequent similar requests for the remainder of this session.
• "reject": Rejects the request.

Example Logic:

from kimi_agent_sdk import ApprovalRequest

async def handle_approvals(msg):
    if isinstance(msg, ApprovalRequest):
        if msg.action == "run shell command":
            await msg.resolve("approve")
        else:
            await msg.resolve("reject")

The prompt() function yields Message instances (specifically kosong.message.Message). Each message contains structured data about the agent's response or tool execution.

Message Fields:

• role: The sender's role (assistant or tool).
• content: A list of ContentPart objects (text, thinking, images, audio, video). Even single strings are stored as a list of parts.
• tool_calls: List of tool call requests (only for assistant role).
• tool_call_id: The ID associated with a tool response (only for tool role).

Common Tasks:

• Extracting Text: Use message.extract_text() to easily get a concatenated string of all text parts in the message.
• Inspecting Structure: Access message.content directly to inspect specific ContentPart types like TextPart or ToolCall.

from kimi_agent_sdk import Message, TextPart, ToolCall

# Example: Assistant message with tool calls
message = Message(
    role="assistant",
    content=[TextPart(text="Let me check the current directory.")],
    tool_calls=[
        ToolCall(
            id="tc_1",
            type="function",
            function={"name": "Shell", "arguments": "{\"command\":\"ls\"}"},
        )
    ],
)

# Example: Tool message responding to a call
tool_message = Message(
    role="tool",
    tool_call_id="tc_1",
    content=[TextPart(text="file1.py\nfile2.py")],
)

The SDK automatically maps Go types to JSON Schema types for your tool's argument structs.

Type Mappings

Required vs Optional Fields

• Required: Fields are required by default.
• Optional: A field becomes optional if:
  1. The json tag includes omitempty or omitzero (e.g., Limit int json:"limit,omitempty"``).
  2. The field is a pointer type (e.g., Options *SearchOptions).

Field Descriptions

Use the description struct tag to provide context to the model for specific fields:

type SearchArgs struct {
    Query  string `json:"query" description:"The search query string"`
    Limit  int    `json:"limit,omitempty" description:"Maximum number of results"`
}

Unsupported Types

kimi.CreateTool will return an error if your argument struct contains:

• func types
• interface{} / any (with some exceptions)
• chan types