Tool Development Guide

Create custom tools with the CallableTool2 + Params pattern, then register them in a YAML agent file.

Quick Template

"""Brief description of what this tool does."""
from kimi_agent_sdk import CallableTool2, ToolError, ToolOk, ToolReturnValue

class Params(BaseModel):
    """Define tool parameters here."""
    required_param: str = Field(
        description="Description of this parameter for the LLM."
    )
    optional_param: str | None = Field(
        default=None,
        description="Optional parameter with default value."
    )

class MyTool(CallableTool2):
    name: str = "MyTool" # Tool identifier
    description: str = "What this tool does."  # For LLM to understand usage
    params: type[Params] = Params # Link to Params class

    async def __call__(self, params: Params) -> ToolReturnValue:
        """Execute the tool logic."""
        try:
            # Your tool logic here
            result = f"Processed: {params.required_param}"
            return ToolOk(output=result)
        except Exception as e:
            return ToolError(
                message=str(e),
                output="Partial output if available",
                brief="Short error summary"
            )

Key Patterns

• Return values: ToolOk(output=...) on success; ToolError(message=..., output=..., brief=...) on failure.
• Validators: ge/le/gt/lt (numeric), min_length/max_length/pattern (strings/collections), default_factory for mutable defaults.
• Best practices: type hints everywhere; clear Field(description=...); always async __call__; handle exceptions → ToolError; one tool = one job.

Registration

Every new tool must be registered in a YAML agent file as "module.path:ClassName" under tools:. KimiToolset.load_tools() splits on the last :, imports the module, gets the class, instantiates, and adds it. Agent files: agent_worker.json (default), agent_boss.json, agent_subagent.json; base agents in kimi-cli/src/kimi_cli/agents/default/ (agent.yaml, coder.yaml, explore.yaml, plan.yaml). Child YAML tools: replaces the parent's list; use allowed_tools:/exclude_tools: to restrict. Use kimi_cli.tools.* prefix for new tools under kimi-cli/src/kimi_cli/tools/; the relocated shell / process / background-job infra (bash, pwsh, Run, FindStr, job_output, common, security, prompt_common) lives under kimi-cli/src/kimi_cli/tools/ and must be imported as kimi_cli.tools.*.

Full complete example, Params reference, background-task tools, interactive-session reuse, and YAML details: read references/guide.md.