API - Tools

Tool 接口

interface Tool {
  name: string
  description: string
  parameters: Record<string, unknown>  // JSON Schema
  execute(args: Record<string, unknown>): Promise<ToolResult>
  requireApproval?: boolean
  sequential?: boolean
}

---

ToolResult

interface ToolResult {
  success: boolean
  content: string
  severity?: "info" | "warning" | "error" | "critical"
  errorCode?: ToolErrorCode
}

enum ToolErrorCode {
  SUCCESS = "SUCCESS"
  UNKNOWN_TOOL = "UNKNOWN_TOOL"
  CIRCUIT_OPEN = "CIRCUIT_OPEN"
  EXECUTION_FAILURE = "EXECUTION_FAILURE"
  ARGUMENTS_PARSE_ERROR = "ARGUMENTS_PARSE_ERROR"
  TRUNCATED_OUTPUT = "TRUNCATED_OUTPUT"
  INTERNAL_ERROR = "INTERNAL_ERROR"
  APPROVAL_DENIED = "APPROVAL_DENIED"
  VALIDATION_ERROR = "VALIDATION_ERROR"
}

辅助函数

import { toolSuccess, toolError } from 'kagent-ts'

// 创建成功结果
toolSuccess(content: string): ToolResult

// 创建错误结果
toolError(code: ToolErrorCode, content: string): ToolResult

---

ToolRegistry

import { ToolRegistry } from 'kagent-ts'

const registry = new ToolRegistry()

方法

class ToolRegistry {
  register(tool: Tool): void
  registerAll(tools: Tool[]): void
  registerAllBuiltinTools(): void
  lookup(name: string): Tool | undefined
  getAll(): Tool[]
  remove(name: string): boolean
  execute(name: string, args: Record<string, unknown>): Promise<ToolResult>
  forSubAgent(filter: ToolFilter): ToolRegistry
}

---

CircuitBreaker

import { CircuitBreaker } from 'kagent-ts'

new CircuitBreaker(config: CircuitBreakerConfig)

interface CircuitBreakerConfig {
  toolName: string             // 工具名称
  retryCount?: number          // 首次失败后的重试次数 (默认: 2)
}

enum BreakerState {
  CLOSED = "closed"            // 正常 — 无失败
  HALF_OPEN = "half_open"      // 半熔断 — 已有失败但工具仍可用
  OPEN = "open"                // 熔断 — 工具被阻止
}

interface BreakerStatus {
  toolName: string
  state: BreakerState
  failureCount: number
  failureThreshold: number
  available: boolean
}

---

Tool Filters

import {
  allowlist,
  denylist,
  pattern,
  all,
  any,
  filterTools,
} from 'kagent-ts'

type ToolFilter = (tool: Tool) => boolean

allowlist(...names: string[]): ToolFilter
denylist(...names: string[]): ToolFilter
pattern(regex: RegExp): ToolFilter
all(...filters: ToolFilter[]): ToolFilter
any(...filters: ToolFilter[]): ToolFilter
filterTools(tools: Tool[], filter: ToolFilter): Tool[]

---

ToolValidator

import { validateToolArgs } from 'kagent-ts'

validateToolArgs(tool: Tool, args: Record<string, unknown>): ValidationResult

---

ToolOutputTruncator

import { ToolOutputTruncator } from 'kagent-ts'

class ToolOutputTruncator {
  constructor(maxSize?: number)  // 默认: 200KB
  truncate(output: string, toolName: string): string
}

---

ToolErrorTracker

会话内的工具失败链追踪（纯内存，无持久化）。用于支撑 list_errors 工具的实时查询。

注意：跨会话的错误学习和规则注入请使用 ErrorNotebook（错题本），它通过 LLM 反思提供更高质量的错误诊断。

import { ToolErrorTracker, categorizeError } from 'kagent-ts'

const tracker = new ToolErrorTracker()

class ToolErrorTracker {
  constructor()
  recordFailure(toolName: string, args: object, error: string, retriesRemaining: number, breakerState?: string): string
  recordRecovery(toolName: string, traceId: string, resolution?: string): void
  recordAnalysis(traceId: string, analysis: string): void
  getActiveTraceId(toolName: string): string | undefined
  getActiveTraces(): Array<{ toolName: string; traceId: string }>
  getAllSummaries(): ErrorTraceSummary[]
  generateMarkdownReport(): string
  clear(): void
}

---

内置工具

import {
  BUILTIN_TOOLS,               // Tool[]
  BUILTIN_TOOL_NAMES,          // string[]
  registerAllBuiltinTools,     // (registry: ToolRegistry) => void
  ReadFileTool,
  WriteFileTool,
  EditFileTool,
  GrepSearchTool,
  GlobSearchTool,
  createSkillTool,
  createRememberTool,
  createRecallTool,
  createListSubagentsTool,
  createSpawnSubagentTool,
  createListErrorsTool,
} from 'kagent-ts'

下一步

• API - Messages — Message 类型 API
• API - Session — Session API
• API - Context — Context & Compression API