tool · diff
git:20260816.ff0cd32 to git:20261010.e311a56
1 added, 1 removed. Audit A to A.
---
name: tool
description: Guide for creating tools using CallableTool2 and Params pattern, plus YAML agent registration
---
# Tool Development Guide
Create custom tools with the `CallableTool2` + `Params` pattern, then register them in a YAML agent file.
## Quick Template
```python
"""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 `kimix.tools.*` prefix for new tools under `src/kimix/tools/`.
+ 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`.