Agent 工具调用设计清单：参数、权限与失败处理

// ❌ 坏：描述模糊，模型需要猜测
const searchUserTool = {
  name: "search_user",
  description: "搜索用户",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string" },
    },
    required: ["query"],
  },
};

// ✅ 好：描述明确，模型能做出正确决策
const searchUserTool = {
  name: "user_search",
  description: [
    "按姓名、邮箱或团队 ID 搜索组织内活跃用户。",
    "适用场景：需要查找某人的联系方式、确认用户是否存在、获取 user_id 用于后续操作。",
    "不适用：查询用户权限请用 `permission_get_user_permissions`；",
    "查询已注销用户请用 `user_search_archived`。",
    "返回最多 20 条结果，支持 cursor 分页。",
  ].join(" "),
  parameters: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "搜索关键词，支持姓名、邮箱地址或团队 ID，至少 2 个字符",
        minLength: 2,
      },
      team_id: {
        type: "string",
        description: "可选，限定搜索范围为指定团队",
        format: "uuid",
      },
      limit: {
        type: "integer",
        description: "返回数量上限，默认 20，最大 50",
        default: 20,
        minimum: 1,
        maximum: 50,
      },
    },
    required: ["query"],
  },
};

// ❌ 坏：类型过宽，无约束
{
  "type": "object",
  "properties": {
    "user": {},
    "action": { "type": "string" },
    "data": { "type": "object" }
  }
}

// ✅ 好：类型精确，约束完整
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid",
      "description": "目标用户 ID，从 `user_search` 返回值获取"
    },
    "action": {
      "type": "string",
      "enum": ["suspend", "activate", "reset_password"],
      "description": "要执行的操作类型"
    },
    "reason": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500,
      "description": "操作原因，用于审计日志，至少 10 个字符"
    },
    "dry_run": {
      "type": "boolean",
      "default": false,
      "description": "为 true 时只校验不执行，用于预览操作影响"
    }
  },
  "required": ["user_id", "action", "reason"]
}

// ❌ 坏：所有工具同等执行，无权限分级
async function executeTool(name: string, params: unknown) {
  const tool = tools[name];
  return await tool.execute(params);
}

// ✅ 好：基于风险等级分层执行
async function executeTool(
  name: string,
  params: unknown,
  context: AgentContext
) {
  const tool = tools[name];
  const riskLevel = tool.metadata.riskLevel;
 
  // L0/L1 直接执行
  if (riskLevel <= RiskLevel.LOW_WRITE) {
    return await tool.execute(params);
  }
 
  // L2 展示预览，等待确认
  if (riskLevel === RiskLevel.MEDIUM_WRITE) {
    const preview = await tool.preview(params);
    const confirmed = await context.requestUserConfirmation(preview);
    if (!confirmed) {
      return { status: "cancelled", reason: "user_declined" };
    }
    return await tool.execute(params);
  }
 
  // L3/L4 拒绝直接执行，生成操作计划
  return {
    status: "requires_approval",
    plan: await tool.generatePlan(params),
    approver: tool.metadata.requiredApprover,
  };
}

// ❌ 坏：自由文本错误，模型难以解析
return { error: "Something went wrong while processing your request" };

// ❌ 稍好但仍然不够：有错误码但无修复建议
return { error_code: "USER_NOT_FOUND", message: "User not found" };

// ✅ 好：结构化错误，带修复建议和可重试标识
return {
  status: "error",
  error_type: "resource_not_found",
  error_code: "USER_NOT_FOUND",
  detail: `未找到 user_id 为 ${params.user_id} 的用户`,
  suggestion: "请确认 user_id 是否正确，可使用 user_search 工具按姓名或邮箱搜索",
  retryable: false,
  trace_id: context.traceId,
};

// ✅ 好：参数校验错误的结构化响应
return {
  status: "error",
  error_type: "validation_error",
  error_code: "INVALID_PARAMETER",
  detail: "参数校验失败",
  fields: [
    {
      field: "action",
      message: `"${params.action}" 不是合法操作类型`,
      allowed_values: ["suspend", "activate", "reset_password"],
    },
    {
      field: "reason",
      message: "操作原因至少需要 10 个字符",
      min_length: 10,
    },
  ],
  suggestion: "请修正上述字段后重试",
  retryable: true,
  trace_id: context.traceId,
};

// ❌ 坏：只记录工具名和参数，无法追溯
console.log(`Tool called: ${name}`, params);

// ✅ 好：结构化审计记录
interface AuditRecord {
  trace_id: string;
  tool_call_id: string;
  tool_name: string;
  caller: {
    agent_id: string;
    session_id: string;
    model: string;
  };
  parameters: Record<string, unknown>; // 敏感字段脱敏后
  risk_level: RiskLevel;
  result_status: "success" | "error" | "cancelled" | "requires_approval";
  result_summary?: string;
  duration_ms: number;
  timestamp: string;
  human_approved: boolean;
  approval_by?: string;
}
 
async function executeWithAudit(
  name: string,
  params: unknown,
  context: AgentContext
) {
  const tool = tools[name];
  const startTime = Date.now();
  const sanitizedParams = sanitizeForAudit(params, tool.metadata.sensitiveFields);
 
  const record: AuditRecord = {
    trace_id: context.traceId,
    tool_call_id: generateToolCallId(),
    tool_name: name,
    caller: {
      agent_id: context.agentId,
      session_id: context.sessionId,
      model: context.model,
    },
    parameters: sanitizedParams,
    risk_level: tool.metadata.riskLevel,
    result_status: "success",
    duration_ms: 0,
    timestamp: new Date().toISOString(),
    human_approved: context.humanApproved ?? false,
    approval_by: context.approvedBy,
  };
 
  try {
    const result = await tool.execute(params);
    record.result_summary = summarizeResult(result);
    record.duration_ms = Date.now() - startTime;
    await auditLogger.write(record);
    return result;
  } catch (err) {
    record.result_status = "error";
    record.result_summary = err instanceof Error ? err.message : String(err);
    record.duration_ms = Date.now() - startTime;
    await auditLogger.write(record);
    throw err;
  }
}